症状

docker-compose up 実行時に network "ネットワーク名" declared as external, but could not be found または network not found エラーが表示される。

結論：まずこれを確認

  1. docker network ls で対象ネットワークが存在するか確認する
  2. 存在しない場合は docker network create ネットワーク名 で作成する
  3. 名前が一致しているか docker-compose.yml の networks セクションを確認する

トラブルシューティングフロー

    flowchart TD
    A[network not found エラー発生] --> B{docker network ls で<br>ネットワークが存在する?}
    B -->|存在しない| C{external: true<br>が設定されている?}
    B -->|存在する| D{名前が完全一致<br>している?}
    C -->|Yes| E[手動でネットワークを作成]
    C -->|No| F[docker-compose down -v 後<br>再度 up を実行]
    D -->|Yes| G[Docker Desktop/デーモン<br>を再起動]
    D -->|No| H[docker-compose.yml の<br>ネットワーク名を修正]
    E --> I[解決]
    F --> I
    G --> I
    H --> I

よくある原因

  • 外部ネットワークが未作成 - external: true を指定したが、ネットワークを事前に作成していない
  • ネットワーク名の不一致 - docker-compose.yml と実際のネットワーク名が異なる（プロジェクト名のプレフィックスを含む/含まない）
  • 以前のネットワークが削除されている - docker-compose down -v や docker system prune でネットワークが削除された
  • プロジェクト名の変更 - ディレクトリ名変更や -p オプションでプロジェクト名が変わった
  • Docker デーモンの再起動 - デーモン再起動後にネットワーク情報がリセットされた（一部環境）
  • typo（タイプミス） - ネットワーク名のスペルミス

確認手順

ステップ1: 現在のネットワーク一覧を確認する

    docker network ls

🔍 チェックポイント: エラーメッセージに表示されたネットワーク名が一覧に存在するか確認する

出力例：

    NETWORK ID     NAME              DRIVER    SCOPE
a1b2c3d4e5f6   bridge            bridge    local
g7h8i9j0k1l2   host              host      local
m3n4o5p6q7r8   myapp_default     bridge    local

ステップ2: docker-compose.yml のネットワーク定義を確認する

    grep -A 10 "^networks:" docker-compose.yml

🔍 チェックポイント: external: true が設定されているか、ネットワーク名が正しいか確認する

確認すべき箇所：

    networks:
  shared_network:
    external: true  # この場合、事前にネットワークが存在する必要がある
    name: actual_network_name  # name が指定されている場合はこの名前で確認

ステップ3: ネットワークが存在しない場合は作成する

    # ネットワーク名はエラーメッセージまたは docker-compose.yml から確認
docker network create ネットワーク名

🔍 チェックポイント: docker network ls で作成したネットワークが表示されることを確認する

ステップ4: ネットワーク名のプレフィックスを確認する

    # プロジェクト名を確認（デフォルトはディレクトリ名）
basename $(pwd)

# 実際に作成されるネットワーク名の形式
# {プロジェクト名}_{networks で定義した名前}

🔍 チェックポイント: docker network ls の NAME カラムと、docker-compose.yml の定義が一致しているか確認する

ステップ5: 既存のネットワークを再作成する

external でない場合：

    # 既存のリソースを削除
docker-compose down

# ネットワークを含めて再作成
docker-compose up -d

🔍 チェックポイント: エラーなく起動することを確認する

NG行動（やってはいけないこと）

  • docker system prune -a を安易に実行する - 他のプロジェクトのネットワークやボリュームも削除される
  • エラーメッセージを読まずにネットワークを作成する - 名前を間違えると解決しない
  • external: true を削除して対処する - 他のコンテナと共有しているネットワークの場合、通信できなくなる
  • ネットワーク名を変更せずに複数回 up を実行する - 同じエラーが繰り返される

よくある質問（FAQ）

Q1: external: true とは何か？

A: Docker Compose の外部で事前に作成されたネットワークを使用する設定。複数の docker-compose.yml 間でネットワークを共有する場合に使う。この設定がある場合、docker-compose up ではネットワークが自動作成されない。

Q2: プロジェクト名のプレフィックスを付けたくない場合は？

A: networks セクションで name を明示的に指定する：

    networks:
  my_network:
    name: my_network  # プレフィックスなしの名前を指定

Q3: 他のコンテナが使用中のネットワークを削除してしまった場合は？

A: 該当のコンテナを停止してから、ネットワークを再作成し、コンテナを再起動する：

    docker stop コンテナ名
docker network create ネットワーク名
docker start コンテナ名

関連するエラー・症状

  • （関連記事準備中）
  • （関連記事準備中）
  • （関連記事準備中）

解決しない場合

  • Docker 公式ドキュメント - Networking in Compose: https://docs.docker.com/compose/networking/
  • 確認すべきログ: docker-compose logs または docker events
  • 次に調べるキーワード: docker network inspect ネットワーク名、docker-compose config（設定の検証）