Lorsque vous travaillez avec des applications multi-conteneurs, vous pouvez rencontrer l’erreur “network not found” lors de l’exécution de docker-compose up. Cela empêche vos conteneurs de démarrer et de communiquer entre eux. Ce guide explique pourquoi cela se produit et fournit des étapes claires pour le résoudre.

L’Erreur

L’erreur ressemble généralement à ceci lorsque vous exécutez docker-compose up :

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.

Ou, dans les versions plus récentes de Docker Compose V2 :

Error response from daemon: network my_custom_network not found

Cause du Problème

Ce problème est presque toujours lié à la façon dont les réseaux sont définis dans votre fichier docker-compose.yml. Les causes les plus courantes sont :

  1. Réseau Externe Manquant : Vous avez déclaré un réseau avec external: true dans votre fichier compose, mais vous n’avez pas encore créé ce réseau dans Docker.
  2. Faute de Frappe dans le Nom du Réseau : Il y a une différence entre le nom du réseau déclaré dans le fichier compose et le réseau réel créé dans Docker.
  3. Réseaux Orphelins : Parfois, si Docker a été redémarré brusquement ou si un démontage précédent a échoué, l’état du réseau interne de Docker peut se désynchroniser.
  4. Différents Contextes Docker : Vous avez créé le réseau dans un contexte Docker (comme un hôte distant) mais vous exécutez compose sur un autre (comme votre machine locale).

Solution Étape par Étape

Étape 1 : Vérifiez l’Existence du Réseau

Tout d’abord, vérifiez si le réseau que Docker Compose recherche existe réellement. Exécutez la commande suivante dans votre terminal :

docker network ls

Recherchez le nom du réseau mentionné dans le message d’erreur. S’il n’est pas dans la liste, cela signifie qu’il n’a pas été créé.

Étape 2 : Créer le Réseau Externe

Si votre docker-compose.yml s’attend à un réseau externe (souvent utilisé pour que plusieurs projets compose distincts puissent communiquer entre eux), vous devez le créer manuellement avant de démarrer les conteneurs.

Créez le réseau en utilisant :

docker network create my_custom_network

(Remplacez my_custom_network par le nom figurant dans votre message d’erreur).

Après l’avoir créé, exécutez à nouveau docker-compose up -d. Cela devrait maintenant fonctionner parfaitement.

Étape 3 : Modifier le fichier docker-compose.yml pour une Création Automatique

Si vous n’avez pas réellement besoin que le réseau soit partagé avec d’autres projets compose indépendants, vous pouvez laisser Docker Compose le gérer automatiquement.

Ouvrez votre docker-compose.yml et regardez le bloc networks en bas :

networks:
  my_custom_network:
    external: true

Modifiez-le pour spécifier simplement le pilote, ou supprimez le paramètre external afin que Docker le crée pour vous :

networks:
  my_custom_network:
    driver: bridge

Remarque : Si Docker Compose crée le réseau automatiquement, il précédera le nom du réseau du nom du répertoire du projet (par exemple, myproject_my_custom_network).

Étape 4 : Nettoyer les Réseaux Docker (Si le réseau devrait exister mais pose problème)

Si docker network ls affiche le réseau mais que Docker Compose soutient toujours qu’il est introuvable, l’état de votre réseau Docker pourrait être corrompu.

Vous pouvez supprimer les réseaux Docker inutilisés et réessayer :

docker network prune

(Avertissement : Cette opération supprimera tous les réseaux personnalisés qui ne sont pas actuellement utilisés par au moins un conteneur).

Solution Alternative : Spécifier le Nom du Réseau Explicitement

Si vous utilisez Docker Compose V2 et souhaitez forcer un nom de réseau spécifique sans utiliser external: true, vous pouvez utiliser la propriété name :

networks:
  my_custom_network:
    name: my_explicit_network_name
    driver: bridge

Ceci indique à Docker Compose de créer le réseau avec ce nom exact, en ignorant la convention habituelle du préfixe de dossier.

Prévention

Pour éviter cette erreur à l’avenir :

  • Documentez les Dépendances Externes : Si votre projet nécessite un réseau externe, documentez-le clairement dans votre fichier README.md.
  • Utilisez des Scripts d’Initialisation : Pour les configurations complexes, fournissez un script setup.sh ou une cible Makefile qui exécute docker network create ... || true avant d’exécuter docker-compose up.
  • Évitez le paramètre External Lorsque ce n’est Pas Nécessaire : Gardez les réseaux internes au fichier compose à moins que vous n’ayez explicitement besoin qu’ils s’étendent sur plusieurs déploiements distincts.

Résumé

  • L’erreur “network not found” signifie que Docker Compose essaie de connecter des conteneurs à un réseau qui n’existe pas.
  • Cela se produit généralement lorsque external: true est défini dans le fichier compose, mais que le réseau n’a pas été créé manuellement.
  • Corrigez ce problème en créant le réseau au préalable avec docker network create <nom>.
  • Alternativement, supprimez external: true pour laisser Docker Compose gérer la création du réseau automatiquement.

Articles Connexes