Bei der Arbeit mit Multi-Container-Anwendungen kann nach dem Ausführen von docker-compose up der Fehler “network not found” auftreten. Dies verhindert, dass Ihre Container gestartet werden und miteinander kommunizieren können. Diese Anleitung erklärt, warum dies geschieht, und enthält klare Schritte zur Fehlerbehebung.

Der Fehler

Der Fehler sieht nach der Ausführung von docker-compose up in der Regel wie folgt aus:

ERROR: Network "my_custom_network" declared as external, but could not be found. Please create the network manually using `docker network create my_custom_network` and try again.

Oder in den neueren Versionen von Docker Compose V2:

Error response from daemon: network my_custom_network not found

Ursache des Problems

Dieses Problem hängt fast immer mit der Art und Weise zusammen, wie Netzwerke in Ihrer docker-compose.yml-Datei definiert sind. Dies sind die häufigsten Ursachen:

  1. Externes Netzwerk fehlt: Sie haben ein Netzwerk in Ihrer Compose-Datei mit external: true deklariert, aber Sie haben dieses Netzwerk in Docker noch nicht erstellt.
  2. Tippfehler im Netzwerknamen: Es gibt eine Abweichung zwischen dem Namen des in der Compose-Datei deklarierten Netzwerks und dem des in Docker tatsächlich erstellten Netzwerks.
  3. Verwaiste Netzwerke: Manchmal kann der interne Netzwerkstatus von Docker asynchron werden, wenn Docker abrupt neu gestartet wurde oder ein vorheriger Abbau (“Teardown”) fehlgeschlagen ist.
  4. Unterschiedliche Docker-Kontexte: Sie haben das Netzwerk in einem Docker-Kontext erstellt (z.B. auf einem entfernten Host), aber Sie führen Compose auf einem anderen aus (z.B. auf Ihrem lokalen Computer).

Schritt-für-Schritt-Lösung

Schritt 1: Überprüfen, ob das Netzwerk existiert

Überprüfen Sie zunächst, ob das Netzwerk, nach dem Docker Compose sucht, tatsächlich vorhanden ist. Führen Sie den folgenden Befehl in Ihrem Terminal aus:

docker network ls

Suchen Sie nach dem in der Fehlermeldung angegebenen Netzwerknamen. Wenn er nicht in der Liste enthalten ist, wurde er nicht erstellt.

Schritt 2: Erstellen des externen Netzwerks

Wenn Ihre docker-compose.yml ein externes Netzwerk erwartet (oft verwendet, damit mehrere unterschiedliche Compose-Projekte miteinander kommunizieren können), müssen Sie es manuell erstellen, bevor Sie die Container starten können.

Erstellen Sie das Netzwerk unter Verwendung von:

docker network create my_custom_network

(Ersetzen Sie my_custom_network durch den Namen aus Ihrer Fehlermeldung).

Führen Sie nach dem Erstellen docker-compose up -d erneut aus. Nun sollte der Befehl fehlerfrei funktionieren.

Schritt 3: Änderung der docker-compose.yml für automatische Erstellung

Wenn Sie das Netzwerk nicht zwingend für den Austausch mit anderen unabhängigen Compose-Projekten benötigen, können Sie es von Docker Compose automatisch verwalten lassen.

Öffnen Sie Ihre docker-compose.yml und betrachten Sie den networks-Block im unteren Bereich:

networks:
  my_custom_network:
    external: true

Ändern Sie ihn, um lediglich den Treiber (driver) anzugeben, oder entfernen Sie die external-Deklaration komplett, sodass Docker die Erstellung für Sie übernimmt:

networks:
  my_custom_network:
    driver: bridge

Hinweis: Wenn Docker Compose das Netzwerk automatisch erstellt, versieht es den Netzwerknamen mit dem Namen des Projektverzeichnisses als Präfix (z.B. myproject_my_custom_network).

Schritt 4: Docker-Netzwerke bereinigen (Wenn das Netzwerk existieren sollte, jedoch Fehler verursacht)

Sollte docker network ls das Netzwerk zwar anzeigen, Docker Compose aber weiterhin behauten, es könne nicht gefunden werden, könnte Ihr Docker-Netzwerkstatus beschädigt (corrupt) sein.

Sie können in diesen Fällen ungenutzte Docker-Netzwerke entfernen und den Vorgang anschließend wiederholen:

docker network prune

(Achtung: Dadurch werden alle benutzerdefinierten Netzwerke entfernt, die derzeit von keinem Container verwendet werden).

Alternative Lösung: Direkte Angabe des Netzwerknamens

Falls Sie Docker Compose V2 verwenden und einen bestimmten Netzwerknamen erzwingen möchten, ohne jedoch external: true zu verwenden, können Sie hierfür die name-Eigenschaft (property) festlegen:

networks:
  my_custom_network:
    name: my_explicit_network_name
    driver: bridge

Dies weist Docker Compose an, das Netzwerk präzise unter diesem Namen zu erstellen und ignoriert gleichzeitig die ansonsten übliche Ordner-Präfix-Konvention.

Prävention

So vermeiden Sie derartige Fehler in der Zukunft:

  • Dokumentieren Sie externe Abhängigkeiten: Falls Ihr Projekt ein externes Netzwerk zwingend erfordert, dokumentieren Sie dies deutlich sichtbar in Ihrer README.md-Datei.
  • Verwenden Sie Skripte für die Initialisierung: Für komplexe Konfigurationen (Setups) empfiehlt sich die Bereitstellung eines setup.sh-Skripts oder eines entsprechenden Makefile-Ziels, welches docker network create ... || true ausführt, bevor docker-compose up aufgerufen wird.
  • Meiden Sie den Einsatz von “External”, wenn es nicht zwingend erforderlich ist: Verwalten Sie die Netzwerke intern in der Compose-Datei, es sei denn, Sie müssen diese Netzwerke explizit über getrennte Bereitstellungen (Deployments) hinweg verteilen.

Zusammenfassung

  • Der Fehler “network not found” deutet darauf hin, dass Docker Compose versucht, Container mit einem noch nicht existierenden Netzwerk zu verknüpfen.
  • Dies ist gewöhnlich der Fall, wenn external: true im Compose-Eintrag verankert wurde, das besagte Netzwerk allerdings nie auf manuellem Wege eingerichtet worden ist.
  • Beheben Sie diesen Umstand primär, indem Sie im Vorfeld das entsprechende Netzwerk durch einen Aufruf der Form docker network create <name> implementieren.
  • Ebenfalls möglich: Entfernen Sie external: true, um fortan Docker Compose die eigenverantwortliche Einrichtung der Netzwerkumgebung zu übertragen.

Verwandte Artikel