Sửa lỗi 'ERROR: The Compose file is invalid because: Unsupported config option for services' trong Docker Compose

Chuyện gì đã xảy ra

Bạn chạy docker-compose up và gặp ngay lỗi này:

ERROR: The Compose file './docker-compose.yml' is invalid because: Unsupported config option for services

Thường có hai nguyên nhân gây ra lỗi này. Hoặc là file docker-compose.yml của bạn dùng phiên bản schema mà binary Compose đang cài không hỗ trợ, hoặc file đó tham chiếu đến các tùy chọn cấu hình chỉ có mặt (hoặc đã bị loại bỏ) ở một phiên bản format khác.

Điều khó chịu ở đây là: thông báo lỗi không cho biết tùy chọn nào bị lỗi hay tại sao. Bạn phải tự đào sâu tìm hiểu.

Xác định các phiên bản đang dùng

Bắt đầu bằng cách kiểm tra những gì thực sự được cài đặt:

# Binary standalone cũ
docker-compose --version
# Docker Compose V2 (plugin)
docker compose version

Sau đó kiểm tra phiên bản khai báo trong file compose:

head -5 docker-compose.yml

Trường version — như "3.8" hay "2.4" — cho Docker Compose biết dùng schema nào để xác thực. Nếu phiên bản trong file nằm ngoài phạm vi mà binary hỗ trợ, bạn sẽ gặp lỗi này.

Bảng tham chiếu nhanh về tính tương thích phiên bản

• Compose file 2.x → yêu cầu docker-compose v1.6 trở lên
• Compose file 3.0–3.3 → yêu cầu docker-compose v1.13 trở lên
• Compose file 3.7 → yêu cầu docker-compose v1.25 trở lên
• Compose file 3.8 → yêu cầu docker-compose v1.26 trở lên
• Không có trường version (Compose spec) → yêu cầu Docker Compose V2 (plugin)

Nguyên nhân phổ biến và cách khắc phục

Nguyên nhân 1: File khai báo phiên bản quá mới so với binary đang cài

Ví dụ file docker-compose.yml của bạn bắt đầu bằng version: "3.8" nhưng bạn đang chạy docker-compose 1.24.x. Binary đó ra đời trước khi 3.8 tồn tại — nó không biết gì về các tính năng của 3.8.

Cách sửa A — Nâng cấp docker-compose:

# Trên Linux (thay bằng phiên bản mới nhất)
sudo curl -L "https://github.com/docker/compose/releases/download/v2.27.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
docker-compose --version

Cách sửa B — Hạ thấp trường version trong file của bạn:

# Đổi từ:
version: "3.8"

# Sang phiên bản mà binary của bạn hỗ trợ, ví dụ:
version: "3.4"

Chỉ dùng cách sửa B nếu bạn không thực sự dùng các tùy chọn riêng của 3.8 — chẳng hạn configs với external templates hay deploy.rollback_config.

Nguyên nhân 2: Không có trường version — định dạng Compose Spec chạy trên binary V1

Bỏ qua trường version là hợp lệ trong Compose Spec hiện đại. Nhưng định dạng đó chỉ được Compose V2 (plugin docker compose) hiểu. Binary standalone docker-compose cũ không xử lý được.

# Sai: dùng binary cũ
docker-compose up   # lỗi với file Compose Spec

# Đúng: dùng plugin V2
docker compose up

Bị kẹt trên hệ thống chỉ có V1? Hãy thêm khai báo version rõ ràng vào file:

version: "3.8"
services:
  app:
    image: myapp:latest
    ...

Nguyên nhân 3: Dùng tùy chọn không tồn tại trong phiên bản đã khai báo

Một số tùy chọn bị giới hạn theo phiên bản. Ví dụ init: true được giới thiệu từ Compose file format 3.7. Khai báo version: "3.4" mà dùng init: true trong cùng file, bạn sẽ gặp lỗi này mỗi lần chạy.

# Gây lỗi với version: "3.4"
services:
  app:
    image: myapp
    init: true   # introduced in 3.7

Cách sửa rất đơn giản — tăng trường version lên khớp với tùy chọn bạn đang dùng:

version: "3.7"   # now init: true is valid
services:
  app:
    image: myapp
    init: true

Nguyên nhân 4: Lỗi đánh máy hoặc thụt lề sai trong YAML

Không phải mọi lỗi "unsupported config option" đều là vấn đề về phiên bản. YAML bị lỗi cú pháp cũng bị báo theo cách tương tự. Một key bị thụt lề sai cấp trông giống như một tùy chọn không xác định với Docker Compose — vì nó không tìm được chỗ đặt key đó trong schema.

# Sai: 'ports' bị thụt lề sai cấp
services:
  app:
    image: nginx
  ports:        # sai! phải nằm dưới 'app'
    - "80:80"

# Đúng:
services:
  app:
    image: nginx
    ports:      # thụt lề đúng dưới service
      - "80:80"

Dán file của bạn vào YAML ↔ JSON Converter trên ToolCraft để phát hiện nhanh các lỗi này. Công cụ chuyển đổi YAML sang JSON hoàn toàn trên trình duyệt — không có gì được tải lên — và các vấn đề về cấu trúc sẽ hiện ra ngay lập tức.

Xác định chính xác tùy chọn nào đang gây lỗi

"Unsupported config option" cho bạn biết có gì đó sai. Nhưng không nói là cái gì. Chạy với --verbose để lấy thêm thông tin:

docker-compose --verbose config 2>&1 | head -40

Hoặc đơn giản là xác thực file mà không khởi động gì cả:

docker-compose config

Lệnh này phân tích file compose và in ra cấu hình đã được giải quyết. Các vấn đề về cấu trúc sẽ hiện ra ở đây với đôi chút ngữ cảnh hơn so với thông báo lỗi ban đầu.

Kiểm tra xem lỗi đã được sửa chưa

# 1. Xác thực file được phân tích không có lỗi
docker compose config
# hoặc với V1:
docker-compose config

# 2. Chạy thử để xác nhận các service được nhận dạng đúng
docker compose config --services

# 3. Khởi động ở chế độ detached
docker compose up -d

# 4. Xác nhận các container đang chạy
docker compose ps

Kết quả sạch từ docker compose config — không có lỗi, chỉ có cấu hình đã được merge — có nghĩa là bạn đã xong.

Những điều cần ghi nhớ

• Khai báo phiên bản Compose file một cách có chủ đích. Sao chép version: "3.8" từ một hướng dẫn nào đó thì ổn — chỉ cần xác minh binary Compose trong môi trường CI của bạn thực sự hỗ trợ phiên bản đó trước.
• Chuyển sang Compose V2 (docker compose). Docker đã chính thức khai tử binary V1 standalone vào năm 2023. Nếu CI hoặc server của bạn vẫn gọi docker-compose, hãy chuyển đổi sớm hơn là muộn. V2 hỗ trợ Compose Spec và vẫn được duy trì tích cực.
• Kiểm tra YAML trước khi commit. Mất 10 giây dán vào công cụ YAML của ToolCraft là đủ để phát hiện lỗi thụt lề trước khi chúng chạm đến pipeline của bạn.
• Dùng docker compose config làm bước chẩn đoán đầu tiên. Lệnh này xác thực file mà không khởi động bất kỳ container nào — cách nhanh nhất để loại trừ vấn đề cấu trúc.