【解決】Docker Compose: network x specified was not found エラーを徹底解説！ネットワーク不整合の落とし穴

Docker Composeを使ってプロジェクトを立ち上げようとしたら、突然「Docker Compose: network x specified was not found」というエラーが出て、「あれ、ネットワークは定義したはずなのに…？」と頭を抱えていませんか？ そうですよね、多くの開発者が一度はハマる、地味だけど厄介なエラーなんです。私も初めて遭遇した時は、一体何が原因なのか分からず、ずいぶん時間を溶かした覚えがあります。

結論から言うと、このエラーの主な原因は、docker-compose.ymlで指定されたネットワークがDockerデーモン上に存在しないか、正しく参照できていないことです。解決策としては、docker-compose.ymlのネットワーク定義の徹底的な確認、ネットワークの再作成、あるいは外部ネットワークの正しい指定が挙げられます。この記事では、あなたの悩みをスパッと解決するための具体的な手順と、再発防止策までしっかり解説していきます！

1. エラーコード Docker Compose: network x specified was not found とは？（概要と緊急度）

この「network x specified was not found」エラーは、Docker Composeが起動しようとしているサービスが、そのサービスが接続しようとしているネットワーク（エラーメッセージの「x」の部分）を見つけられなかった、という意味です。

つまり、Docker Composeがコンテナを作成・起動する際に、「このコンテナは『my_network』という名前のネットワークに繋ぎたいんだけど、どこにもそんなネットワークが見当たらないよ！」と教えてくれている状態です。このエラーが発生すると、対象のコンテナは起動できず、したがってアプリケーション全体も正しく動作しません。

🚨 緊急度は高め！サービスが起動できません

このエラーが出ると、指定されたネットワークに依存するコンテナが起動しないため、アプリケーション全体が正常に動作しません。開発環境であれば作業が止まり、本番環境であればサービス停止につながる可能性もあります。早急な対応が必要です。

2. 最速の解決策 3選

さあ、ここからは具体的な解決策を見ていきましょう。一つずつ試してみてください。

解決策1: docker-compose.ymlのネットワーク定義とサービスへの適用を確認する

真っ先に確認すべきは、あなたのdocker-compose.ymlファイルです。 ほとんどの場合、ここでの設定ミスが原因です。

  • ネットワークがnetworks:セクションで正しく定義されているか？

    docker-compose.ymlの最下部に、networks:セクションがあり、そこであなたの使いたいネットワークが定義されているかを確認してください。

    # 例: ネットワークが定義されているか確認
version: '3.8'
services:
  web:
    image: nginx
    networks:
      - my_network # ここで指定するネットワーク名

  db:
    image: postgres
    networks:
      - my_network # ここで指定するネットワーク名

networks:
  my_network: # ★ここ！このネットワーク名が services の networks と一致しているか？
    driver: bridge # 通常は bridge でOK
  • 各サービスがそのネットワークを正しく参照しているか？

    上記例のように、各サービス（webやdb）のnetworks:セクションで、定義したネットワーク名が正しく記述されているかを確認します。スペルミスや大文字・小文字の間違いは致命的です！

  • インデントミスがないか？

    YAMLファイルではインデント（字下げ）が非常に重要です。インデントが間違っていると、Docker Composeは設定を正しく解釈できません。

💡 設定ファイルの検証に docker-compose config を活用しよう！

docker-compose configコマンドを実行すると、docker-compose.ymlファイルに構文エラーがないか、そして最終的にDocker Composeがどういう設定として解釈するのかを確認できます。エラーが出たら、まずはこれを実行してデバッグのヒントを探しましょう。

docker-compose config

解決策2: 既存のDockerネットワークをクリーンアップ・再構築する

docker-compose.ymlの設定は正しいはずなのに…という場合は、Dockerデーモン側のネットワークの状態に問題がある可能性があります。過去に作成されたネットワークの残骸や、何らかの理由で状態が不整合になっていることがあります。

  • 作成済みのネットワークを確認する

    まずは現在Docker上に存在するネットワークの一覧を確認してみましょう。

    docker network ls

    もしここに、docker-compose.ymlで指定しているネットワーク名と同じものがあり、それが古いものだったり、意図しない状態だった場合は、一度削除して再作成を試みます。

  • 問題のネットワークを削除して再作成する

    もしdocker network lsで、エラーになっているネットワーク名（例: my_network）が見つかり、それが原因だと思われる場合は、一度削除してみましょう。

    docker network rm my_network

    その後、再度docker-compose up -dを実行すれば、Docker Composeがdocker-compose.ymlの定義に基づいて新しいネットワークを作成してくれるはずです。

  • より強力なクリーンアップ（最終手段）

    もし上記の個別削除でも解決しない場合は、注意が必要ですが、Docker環境全体のクリーンアップを試すこともできます。これは、停止しているコンテナ、使用されていないネットワーク、イメージなどをまとめて削除するコマンドです。

    docker system prune

    さらに、ボリュームも削除したい場合は-aオプションを追加します（データが消えるので特に注意！）。

    docker system prune -a --volumes

🚨 docker system prune の使用は慎重に！

docker system pruneコマンドは、停止中のコンテナ、未使用のネットワーク、キャッシュされたイメージなどをまとめて削除します。特に--volumesオプションを付けると、ボリューム内のデータも削除されるため、必要なデータが消えないよう、実行前には必ずバックアップを取るか、本当に不要なものだけか確認してください。開発環境で試す場合でも、大事なデータベースデータなどがないか確認しましょう。

解決策3: 外部ネットワークを使用する場合の注意点

「既存のネットワークを使いたいからexternal: trueを使ってるんだ！」という方もいるでしょう。その場合は、Docker Composeが起動する前に、その外部ネットワークがDockerデーモン上に存在している必要があります。

  • 外部ネットワークが事前に作成されているか？

    docker-compose.ymlで以下のようにexternal: trueと指定した場合、

    networks:
  my_existing_network:
    external: true # ★ここ！

    このmy_existing_networkという名前のネットワークは、Docker Composeが作成するのではなく、あなたが事前に手動で作成している必要があります。

    以下のコマンドで作成されているか確認し、もしなければ作成してください。

    # 存在するか確認
docker network ls | grep my_existing_network

# 存在しない場合、手動で作成
docker network create my_existing_network
  • external: trueと定義したのに、ネットワークが自動作成されているケース

    たまに見かけるミスとして、networks:セクションでexternal: trueを指定しているにもかかわらず、そのネットワーク名がDocker Composeによって勝手に作成されてしまい、その後に別のコンテナが既存のネットワークを見つけられないというケースがあります。これは、多くの場合、外部ネットワークとして指定したいのに、実際にはDocker Composeが内部的に作成しようとしてしまう設定になっている場合に発生します。

    external: trueを指定する際は、Docker Composeのトップレベルのnetworks:セクションで、すでに存在するネットワークを参照していることを明確にしましょう。

💡 external: true を使う場合の推奨ワークフロー

外部ネットワークを使う場合は、以下の手順を開発・デプロイのワークフローに組み込むことをお勧めします。

  1. ネットワークの作成:
    docker network create my_shared_network
  2. docker-compose.ymlで参照: 
    networks:
  my_shared_network:
    external: true
  3. サービスを起動:
    docker-compose up -d

3. エラーの根本原因と再発防止策

一度解決しても、また同じエラーで悩まされるのは嫌ですよね。根本原因を理解し、再発防止策を講じましょう。

根本原因

  • docker-compose.yml内の設定ミス: 最も多い原因です。スペルミス、インデントの誤り、ネットワーク名の不一致（サービスとnetworks:セクションの間で）など。
  • ネットワークの存在確認不足: 特にexternal: trueを使用する際、Docker Compose起動前にそのネットワークが存在しないケース。
  • Dockerデーモン側のネットワーク状態の不整合: 稀ですが、Dockerの内部的な状態が壊れていて、既存のネットワークが正しく認識されないことがあります。これは再起動やクリーンアップで解決します。

再発防止策

  • docker-compose configを習慣にする: ファイルを編集したら、docker-compose upの前にまずdocker-compose configを実行し、構文チェックと最終的な設定内容を確認しましょう。これにより、多くの設定ミスを未然に防げます。
  • ネットワーク名の統一と確認を徹底する: docker-compose.yml内で使用するネットワーク名は、サービスセクションとnetworks:セクションで完全に一致させてください。コピペを活用し、手動入力によるミスを減らしましょう。
  • 外部ネットワーク使用時の手順を明確にする: external: trueを使う場合は、プロジェクトのセットアップ手順に「docker network createコマンドで〇〇ネットワークを事前に作成すること」と明記し、チームメンバー間で共有しましょう。
  • 定期的なDocker環境のクリーンアップ: 開発環境であれば、定期的にdocker system prune（ただし--volumesなしで）を実行して、不要なリソースを削除し、環境をクリーンに保つことで、不測のトラブルを防ぎやすくなります。
  • バージョン管理システムを活用する: docker-compose.ymlファイルは必ずGitなどのバージョン管理システムで管理し、変更履歴を追えるようにしましょう。もしエラーが発生しても、以前の正常な状態と比較して原因を特定しやすくなります。

4. まとめ

Docker Composeの「network x specified was not found」エラー、もう怖くありませんね！ このエラーは、ほとんどが設定ファイル内のちょっとした記述ミスや、ネットワークの事前準備不足が原因です。焦らず、以下のポイントを思い出してください。

  1. docker-compose.ymlのネットワーク定義が完璧か？ スペル、インデント、参照名を何度も確認。docker-compose configで検証！
  2. 外部ネットワークを使う場合、事前にdocker network createで作成したか？
  3. それでもダメなら、Docker環境のネットワーク状態をリフレッシュ（削除＆再作成）してみる。

Docker Composeは非常に便利ですが、設定一つでうまく動かなくなってしまうこともあります。でも、この記事を読んで対処法を知ったあなたは、もう大丈夫。これからも快適なDockerライフを楽しんでくださいね！

“`

Related Posts