Docker Composeの「ERROR: The Compose file is invalid because: Unsupported config option for services」を修正する

何が起きたか

docker-compose up を実行したら、次のエラーが表示された：

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

原因は主に2つある。インストールされている Compose バイナリが対応していないスキーマバージョンを docker-compose.yml が使用しているか、異なるファイルフォーマットバージョンで追加（または削除）された設定オプションを参照しているかのどちらかだ。

厄介なのは、このエラーメッセージがどのオプションが失敗したか、なぜ失敗したかを教えてくれないことだ。自分で調べなければならない。

使用中のバージョンを確認する

まず、実際にインストールされているものを確認しよう：

# 旧来のスタンドアロンバイナリ
docker-compose --version
# Docker Compose V2（プラグイン）
docker compose version

次に、compose ファイルで宣言されているバージョンを確認する：

head -5 docker-compose.yml

"3.8" や "2.4" のような version フィールドは、Docker Compose にバリデーションで使用するスキーマを指示する。ファイルのバージョンがバイナリのサポート範囲外であれば、このエラーが発生する。

バージョン互換性のクイックリファレンス

Compose ファイル 2.x → docker-compose v1.6+ が必要
Compose ファイル 3.0〜3.3 → docker-compose v1.13+ が必要
Compose ファイル 3.7 → docker-compose v1.25+ が必要
Compose ファイル 3.8 → docker-compose v1.26+ が必要
version フィールドなし（Compose spec） → Docker Compose V2（プラグイン）が必要

よくある原因と対処法

原因 1：インストール済みバイナリが対応していない新しいバージョンをファイルが宣言している

docker-compose.yml が version: "3.8" で始まっているのに、docker-compose 1.24.x を使っている場合を考えてみよう。そのバイナリは 3.8 が存在する前にリリースされたものであり、3.8 の機能を認識できない。

対処法 A — docker-compose をアップグレードする：

# Linux の場合（最新バージョンに置き換えること）
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

対処法 B — ファイルの version フィールドをダウングレードする：

# これを：
version: "3.8"

# バイナリが対応しているバージョンに変更する（例）：
version: "3.4"

対処法 B を選ぶのは、3.8 固有のオプション（外部テンプレートを使った configs や deploy.rollback_config など）を実際には使っていない場合に限ること。

原因 2：version フィールドなし — V1 バイナリで Compose Spec フォーマットを使用

version フィールドを省略することは、モダンな Compose Spec では有効だ。しかし、そのフォーマットは Compose V2（docker compose プラグイン）でのみ解釈できる。旧来のスタンドアロン docker-compose バイナリはこれを処理できない。

# 誤り：旧来のバイナリを使用
docker-compose up   # Compose Spec ファイルでは失敗する

# 正しい：V2 プラグインを使用
docker compose up

V1 しか使えないシステムで行き詰まっている場合は、ファイルに明示的なバージョン宣言を追加しよう：

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

原因 3：宣言されたバージョンに存在しないオプションを使用している

一部のオプションはバージョンによって使用が制限される。たとえば init: true は Compose ファイルフォーマット 3.7 で導入された。同じファイルで version: "3.4" を宣言しつつ init: true を使うと、毎回このエラーが発生する。

# version: "3.4" ではエラーが発生する
services:
  app:
    image: myapp
    init: true   # 3.7 で導入

対処法は単純で、使用しているオプションに合わせて version フィールドを上げればよい：

version: "3.7"   # これで init: true が有効になる
services:
  app:
    image: myapp
    init: true

原因 4：YAML のタイポや誤ったインデント

「unsupported config option」エラーのすべてがバージョンの問題とは限らない。不正な YAML も同じように誤報告される。インデントレベルが間違っているキーは、Docker Compose からすると未知のオプションに見える——スキーマのどこに配置すべきか判断できないからだ。

# 誤り：'ports' のインデントが間違っている
services:
  app:
    image: nginx
  ports:        # 誤り！'app' の下に置くべき
    - "80:80"

# 正しい：
services:
  app:
    image: nginx
    ports:      # サービスの下に正しくインデント
      - "80:80"

ファイルを ToolCraft の YAML ↔ JSON コンバーターに貼り付けると、これらのミスを素早く見つけられる。ブラウザ上で完全に YAML を JSON に変換するため、何もアップロードされることはなく、構造上の問題がすぐに明らかになる。

実際に失敗しているオプションを特定する

「Unsupported config option」は何かがおかしいことを教えてくれる。しかし何がおかしいかは教えてくれない。--verbose を付けて実行すると、より多くの情報が得られる：

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

または、何も起動せずにファイルだけを検証する：

docker-compose config

このコマンドは compose ファイルをパースして解決済みの設定を出力する。構造上の問題は、元のエラーメッセージより少し多いコンテキストとともにここで表面化する。

修正が効いているか確認する

# 1. ファイルが正常にパースされるか検証
docker compose config
# または V1 の場合：
docker-compose config

# 2. サービスが解決できるかドライラン
docker compose config --services

# 3. デタッチモードで起動
docker compose up -d

# 4. コンテナが起動しているか確認
docker compose ps

docker compose config からエラーなし（マージされた設定のみ）のクリーンな出力が得られれば、作業完了だ。

まとめ

**Compose ファイルのバージョンは意図を持って固定する。**チュートリアルから version: "3.8" をコピーするのは構わないが、CI 環境の Compose バイナリが実際にそれをサポートしているか先に確認すること。
**Compose V2（docker compose）に移行する。**Docker は 2023 年にスタンドアロンの V1 バイナリを公式に非推奨とした。CI やサーバーがまだ docker-compose を呼び出しているなら、後回しにせず早めに移行しよう。V2 は Compose Spec をサポートしており、積極的にメンテナンスされている。
**コミット前に YAML をリントする。**ToolCraft の YAML コンバーターに 10 秒貼り付けるだけで、パイプラインに到達する前にインデントのバグを検出できる。
**最初の診断には docker compose config を使う。**コンテナを一つも起動せずにファイルを検証できる——構造上の問題を排除する最速の方法だ。