Docker Compose v2 で「services.xxx.depends_on contains an invalid type」エラーが出る理由と解決方法

Docker Compose v2 に移行した際、次のようなエラーに遭遇することがあります。

services.xxx.depends_on contains an invalid type

これまで問題なく動いていた docker-compose.yml が、Compose v2 では突然エラーになるため戸惑う人も多いはずです。
本記事では、このエラーが発生する原因と、Compose v2 に対応した正しい depends_on の書き方、既存設定からの移行方法を解説します。

エラーの概要

Compose v2 で厳格になった depends_on の型チェック

このエラーは、depends_on に指定している データ型が期待と異なる 場合に発生します。
特に多いのが、Compose v1 時代に許容されていた書式をそのまま使っているケースです。

Compose v2 では、Compose Specification により厳密に準拠するようになり、曖昧な書き方がエラーとして検出されるようになりました。

よくある原因

旧来の辞書形式を誤って使っている

次のような書き方は、Compose v1 では見かけることがありました。

services:
  app:
    depends_on:
      db: true

この書式は Compose v2 では invalid type と判定されます。
depends_on には「配列」または「条件付き辞書形式」を指定する必要があります。

正しい depends_on の書き方

1. 配列形式（最も基本）

シンプルな依存関係を定義する場合

サービスの起動順だけを制御したい場合は、配列形式を使います。

services:
  app:
    depends_on:
      - db
      - redis

この形式は Compose v2 でも完全にサポートされています。

注意点

• 起動順を保証するだけで、サービスの「起動完了」までは待たない
• ヘルスチェックの完了は考慮されない

2. 辞書形式（条件付き depends_on）

サービスの状態を条件にしたい場合

Compose v2 では、以下の条件付き辞書形式が正式にサポートされています。

services:
  app:
    depends_on:
      db:
        condition: service_healthy

この場合、db サービスの healthcheck が healthy になるまで app は起動しません。

使用可能な condition

• service_started
• service_healthy
• service_completed_successfully

なぜ invalid type になるのか

depends_on は「配列」または「特定構造の辞書」だけが有効

Compose v2 では、次のような指定はすべてエラーになります。

depends_on: db
depends_on: true
depends_on:
  db: true

理由は、Compose Specification において depends_on の型が明確に定義されているためです。

• 配列形式: string[]
• 辞書形式: service -> condition

それ以外の型は受け付けられません。

Compose v1 から v2 への移行時チェックリスト

エラーが出たら確認すべきポイント

• depends_on が配列または正しい辞書形式になっているか
• true / false を値に使っていないか
• YAML のインデントが崩れていないか
• condition を使う場合、依存先に healthcheck が定義されているか

起動順だけで十分なケースと不十分なケース

起動順だけで問題ない例

• 単純なローカル開発環境
• DB がすぐ起動する前提の構成

起動完了を待つべき例

• DB や外部APIの初期化が重い
• マイグレーション処理が必要
• CI 環境や本番相当構成

この場合は service_healthy を使い、healthcheck を正しく設定するのが安全です。

実務でのベストプラクティス

depends_on に過度な期待をしない

depends_on はあくまで 起動制御の補助 です。
アプリケーション側でも以下の対策を行うのが理想です。

• 接続リトライ処理を実装する
• 起動時に依存サービスの疎通確認を行う
• readiness を考慮した設計にする

まとめ

Docker Compose v2 の
「services.xxx.depends_on contains an invalid type」エラーは、仕様に沿っていない書式を使っていることが原因です。

重要ポイント

• Compose v2 では depends_on の型が厳密
• 配列形式または condition 付き辞書形式のみ有効
• db: true のような旧書式は使えない
• 移行時は YAML の構造を必ず見直す

Compose v2 は不親切になったのではなく、曖昧な設定を早期に検知してくれるようになった と考えると理解しやすいです。
このエラーを機に、依存関係の設計も一段階見直してみるとよいでしょう。