Docker « réseau introuvable » : reconstruire les réseaux sans tout casser

Ce que signifie réellement « network not found »

Le réseau Docker est surtout une gestion d’état. Quand vous créez un réseau, Docker enregistre une entrée (nom, ID, driver, paramètres IPAM) dans son état local. Quand un conteneur démarre, Docker demande : « attacher ce point de terminaison au réseau X ». Si Docker ne retrouve pas X par ID, vous obtenez « network not found ».

La partie délicate est que le nom affiché n’est pas la vraie clé. Docker utilise un ID de réseau, et Compose stocke/utilise cet ID en coulisses. Si l’entrée réseau est supprimée, corrompue ou que l’état du démon est réinitialisé, Compose peut encore tenter d’attacher des conteneurs à un ID désormais inexistant. C’est ainsi que vous vous retrouvez avec un réseau qui « existe » dans votre YAML, « existe » dans votre tête, mais pas dans l’état réel de Docker.

Où l’erreur apparaît

• docker run : Error response from daemon: network <id> not found
• docker compose up : échecs lors de la création ou de l’attachement des conteneurs
• Swarm : tâches bloquées avec des erreurs d’attachement réseau
• Après un redémarrage : le démon redémarre et « oublie » les réseaux à cause d’un répertoire d’état cassé ou d’une restauration partielle

Important : « network not found » n’est pas la même chose que « impossible d’atteindre le service ». Ce dernier est généralement lié au routage, iptables/nftables, MTU, DNS ou configuration applicative. « Network not found » est presque toujours un problème de plan de contrôle : Docker ne trouve pas l’objet réseau référencé.

Vérité sèchement drôle : les réseaux Docker ressemblent aux organigrammes. Vous pouvez supprimer la case, mais tout le monde continue d’essayer d’y rendre des comptes.

Playbook de diagnostic rapide (vérifiez ceci en premier)

Ceci est l’ordre qui minimise les dommages collatéraux et vous fait passer du « texte d’erreur » à la « correction » avec le moins de conjectures possible. Le but n’est pas d’être brillant ; il est d’être rapide et correct.

1) Identifier ce qui échoue et quel réseau est demandé

Récupérez l’erreur exacte. Référence-t-elle un nom de réseau ou un ID hexadécimal ? Les IDs indiquent clairement que quelque chose a stocké une référence obsolète.

2) Confirmer si Docker croit que le réseau existe

Si docker network ls ne le montre pas, vous n’avez pas affaire à un problème de paquets. Vous avez affaire à un état manquant.

3) Vérifier si Compose a créé et labelisé un réseau de projet

Les réseaux Compose ont des labels comme com.docker.compose.project. Si ces labels n’existent plus, vous êtes en phase de reconstruction, pas de débogage.

4) Vérifier la santé du démon et les logs avant de « réparer » quoi que ce soit

L’état réseau disparaît pour plusieurs raisons : disque plein, corruption du système de fichiers, crash du démon, ou nettoyage excessif. Traitez cela comme le symptôme d’un problème plus vaste jusqu’à preuve du contraire.

5) Décider du rayon d’impact : projet unique vs hôte entier

Si un seul projet Compose est affecté, ne sacrifiez pas tout l’hôte. Recréez le réseau du projet et rattachez. Si plusieurs réseaux ont disparu, suspectez une corruption de l’état du démon ; vous pourriez devoir faire une réinitialisation contrôlée.

Faits intéressants et un peu d’histoire (parce que ça aide)

1. Le réseau « bridge » de Docker est antérieur aux workflows modernes de Compose. Docker utilisait par défaut le pont docker0 et le NAT iptables ; les réseaux bridge définis par l’utilisateur sont apparus plus tard pour améliorer le DNS et l’isolation.
2. Les réseaux bridge définis par l’utilisateur fournissent un DNS basé sur les noms. Le serveur DNS intégré (typiquement à 127.0.0.11 dans les conteneurs) permet aux conteneurs de résoudre les noms de services sans outil additionnel.
3. Compose v2 est un plugin de la CLI Docker. Le passage d’un outil Python séparé à un plugin a changé l’apparence des erreurs et la gestion des contextes.
4. Les IDs de réseau sont des identifiants opaques de type adressage par contenu. Les humains utilisent des noms ; le démon utilise des IDs. Perdre le mappage transforme les « mais le YAML dit… » en chose sans importance.
5. iptables vs nftables a été une source récurrente de problèmes. Docker programmatique iptables directement ; sur certaines distributions le backend nftables change le comportement et surprend les gens.
6. L’état local de Docker vit sous /var/lib/docker. Si ce répertoire est vidé, restauré partiellement ou monté de façon étrange, les réseaux « disparaissent » avec le reste.
7. Les réseaux overlay ont été conçus pour l’histoire multi-hôtes de Swarm. Même si vous n’utilisez jamais Swarm, le modèle réseau apparaît encore dans les messages d’erreur et les drivers.
8. Les drivers MACVLAN/IPVLAN existent pour contourner le bridge. Ils sont utiles jusqu’à ce que votre équipe réseau en amont les découvre et se demande pourquoi l’hôte ne peut pas parler à ses propres conteneurs.
9. Certaines outils de « nettoyage » suppriment les réseaux plus agressivement que prévu. Tout outil qui prune les objets « inutilisés » peut entrer en course avec des redémarrages ou classer à tort des ressources comme inutilisées.

Une idée paraphrasée à garder sur votre bureau, souvent attribuée à Werner Vogels : tout échoue, tout le temps — concevez et exploitez en supposant que des composants vont casser (idée paraphrasée).

Causes courantes et modes de défaillance

1) Le réseau a été supprimé (parfois « utilement »)

Quelqu’un a exécuté docker network rm sur des réseaux « inutilisés ». Ou un job de nettoyage a lancé un prune. Ou un agent CI sur un hôte partagé a nettoyé après lui et « après lui » incluait vos réseaux.

2) Dérive ou corruption de l’état du démon Docker

Arrêt non propre + problèmes de disque + système de fichiers stressé peuvent produire un état partiel. Docker démarre, mais certains objets manquent. Les réseaux sont souvent les premières victimes car ils sont riches en métadonnées et référencés par des IDs à travers plusieurs objets.

3) Renommage de projet Compose ou déplacement de répertoire

Compose utilise le nom du projet (souvent dérivé du répertoire) pour nommer les ressources. Déplacez le répertoire ou changez COMPOSE_PROJECT_NAME, et vous pouvez obtenir des conteneurs qui attendent des réseaux créés sous l’ancien nom de projet.

4) Plusieurs contextes Docker ou hôte erroné

Vous pensez être en production, mais votre CLI pointe vers un autre contexte Docker. Le réseau « est manquant » parce que vous regardez le mauvais démon. C’est plus courant que les gens l’admettent.

5) Swarm et réseaux overlay dans un état semi-configuré

Les réseaux overlay nécessitent un état de cluster. Si un nœud n’est plus membre du cluster, ou si l’état des managers est incohérent, les tâches peuvent échouer lors de l’attachement réseau.

6) Le pare-feu/iptables/nftables est cassé (mais c’est une autre erreur)

C’est une distraction courante. Des règles NAT cassées produisent généralement des échecs de connectivité, pas « network not found ». Cependant : un redémarrage du démon peut reprogrammer les règles et entrer en collision avec des changements de distribution.

Tâches pratiques : commandes, sorties attendues et décisions

Ce sont de réels gestes opérateurs. Chaque tâche inclut : la commande, ce que la sortie signifie, et la décision suivante. Ne copiez-collez pas aveuglément sur un hôte partagé. Lisez ce que vous faites, puis faites-le.

Task 1: Confirm you’re talking to the right Docker daemon

cr0x@server:~$ docker context show
default

Ce que cela signifie : Vous utilisez le contexte default (démon local). S’il affiche autre chose, vous pourriez déboguer la mauvaise machine.

Décision : Si inattendu, lancez docker context ls, basculez sur le bon contexte, et revérifiez le problème avant de toucher aux réseaux.

Task 2: Verify the daemon is healthy and responsive

cr0x@server:~$ docker info --format '{{.ServerVersion}} {{.OperatingSystem}}'
27.2.0 Ubuntu 24.04.1 LTS

Ce que cela signifie : La CLI peut parler au démon et obtenir des infos structurées. Si cela bloque ou renvoie une erreur, votre problème réseau peut être un problème de démon.

Décision : Si non réactif, vérifiez systemd et les logs d’abord. Ne fouillez pas les réseaux pendant que le démon est malade.

Task 3: List networks and see what exists right now

cr0x@server:~$ docker network ls
NETWORK ID     NAME              DRIVER    SCOPE
1f3a2c1a9e2d   bridge            bridge    local
a9b7b5d41c1f   host              host      local
c3d6f2d51c9a   none              null      local

Ce que cela signifie : Seuls les réseaux par défaut existent. Si votre réseau Compose manque, cela confirme fortement « réseau supprimé » ou « état perdu ».

Décision : Si le réseau ciblé est absent, cessez d’essayer de « connecter » des conteneurs à celui-ci. Prévoyez de le recréer.

Task 4: Find the network reference from a failing container

cr0x@server:~$ docker inspect -f '{{json .NetworkSettings.Networks}}' api_1
null

Ce que cela signifie : Le conteneur n’est attaché à aucun réseau (ou n’existe pas). Si le conteneur a échoué à la création, inspect peut échouer lui aussi.

Décision : Si le conteneur n’existe pas, consultez les événements/logs de Compose ; la référence réseau est probablement dans la sortie d’erreur lors de la création.

Task 5: Inspect a network by name (if you think it exists)

cr0x@server:~$ docker network inspect app_default
[]
Error response from daemon: network app_default not found

Ce que cela signifie : Docker confirme que l’objet réseau est absent.

Décision : Recréez le réseau (habituellement via Compose) plutôt que d’essayer de réparer des attachements.

Task 6: Check Compose’s view of the project

cr0x@server:~$ docker compose ls
NAME            STATUS              CONFIG FILES
app             running(3)          /srv/app/docker-compose.yml

Ce que cela signifie : Docker Compose pense qu’un projet existe. Il peut être encore partiellement en cours d’exécution.

Décision : Si le statut est inconsistant avec la réalité, vous pouvez avoir des conteneurs orphelins ou des réseaux manquants. Étape suivante : docker compose ps.

Task 7: See what Compose thinks is running and what networks it expects

cr0x@server:~$ docker compose -p app ps
NAME      IMAGE          COMMAND               SERVICE   STATUS
app-db-1  postgres:16    "docker-entrypoint…"  db        Up 2 hours
app-api-1 app-api:latest "/bin/api"            api       Exit 1

Ce que cela signifie : Certains services fonctionnent, d’autres échouent. Cela arrive souvent quand un sous-ensemble de conteneurs est attaché à un réseau désormais disparu, ou que le réseau a disparu après des redémarrages.

Décision : Vérifiez les logs du service en échec et les événements ; confirmez que « network not found » est la cause, et non un crash applicatif.

Task 8: Pull the real failure reason from events

cr0x@server:~$ docker events --since 10m --filter type=container --filter event=start --filter event=die
2026-01-03T09:11:26.321615241Z container start 5a8c0e3f8b2b (name=app-api-1, image=app-api:latest)
2026-01-03T09:11:26.412992531Z container die 5a8c0e3f8b2b (exitCode=1, name=app-api-1, image=app-api:latest)

Ce que cela signifie : Le conteneur a démarré puis est mort (exit 1). Ce n’est pas « network not found ». C’est au niveau applicatif.

Décision : Si les événements montrent des échecs de création de conteneurs (les échecs d’attachement réseau y apparaissent souvent), concentrez-vous sur la recréation du réseau. Si le conteneur meurt après démarrage, déboguez les logs applicatifs.

Task 9: Check daemon logs for network store or libnetwork errors

cr0x@server:~$ sudo journalctl -u docker --since "1 hour ago" | tail -n 20
Jan 03 09:03:10 server dockerd[1123]: time="2026-01-03T09:03:10.991132145Z" level=error msg="network sandbox join failed" error="network app_default not found"
Jan 03 09:03:10 server dockerd[1123]: time="2026-01-03T09:03:10.991264223Z" level=error msg="Handler for POST /v1.46/containers/create returned error: network app_default not found"

Ce que cela signifie : Le démon échoue explicitement la création de conteneurs à cause d’un réseau manquant. C’est le cas d’école.

Décision : Recréez app_default (de préférence via docker compose up qui labelise aussi correctement). Évitez la création manuelle sauf si vous devez faire correspondre des paramètres IPAM.

Task 10: Find who “owns” a network (labels matter)

cr0x@server:~$ docker network inspect -f '{{json .Labels}}' app_default
Error response from daemon: network app_default not found

Ce que cela signifie : Introuvable, donc pas de labels à inspecter. Quand il existe, les labels indiquent si Compose l’a créé et quel est le projet.

Décision : Si vous recréez manuellement, vous perdez les métadonnées d’appartenance de Compose à moins de réappliquer les labels (non recommandé). Mieux : laissez Compose créer le réseau.

Task 11: Recreate the network the boring, correct way (Compose)

cr0x@server:~$ cd /srv/app
cr0x@server:/srv/app$ docker compose -p app up -d
[+] Running 4/4
 ✔ Network app_default  Created
 ✔ Container app-db-1   Started
 ✔ Container app-api-1  Started
 ✔ Container app-web-1  Started

Ce que cela signifie : Compose a créé le réseau manquant et démarré les conteneurs. C’est généralement la correction la plus propre.

Décision : Vérifiez la connectivité et le DNS. Si les conteneurs affichent encore « network not found », vous pouvez avoir plusieurs projets ou références obsolètes ; poursuivez avec un nettoyage plus approfondi.

Task 12: Validate the network driver and subnet (catch silent differences)

cr0x@server:~$ docker network inspect -f 'Driver={{.Driver}} Subnet={{(index .IPAM.Config 0).Subnet}}' app_default
Driver=bridge Subnet=172.22.0.0/16

Ce que cela signifie : Confirme le driver et la config IPAM. Si le subnet diffère de ce que vos règles de pare-feu ou listes d’accès attendent, vous aurez « ça démarre mais ça n’atteint rien ».

Décision : Si le subnet doit être stable, fixez-le dans Compose ipam et recréez-le volontairement, pas par accident.

Task 13: Check container resolv.conf and embedded DNS behavior

cr0x@server:~$ docker exec app-api-1 cat /etc/resolv.conf
nameserver 127.0.0.11
options ndots:0

Ce que cela signifie : Le DNS embarqué est utilisé. Si le DNS échoue, c’est souvent parce que le conteneur est sur le mauvais réseau ou que le réseau est cassé.

Décision : Si vous voyez un serveur DNS hôte à la place, vous pourriez utiliser network_mode: host ou des paramètres personnalisés. Cela change la façon de dépanner.

Task 14: Confirm name resolution between services on the network

cr0x@server:~$ docker exec app-api-1 getent hosts db
172.22.0.2      app-db-1

Ce que cela signifie : Le DNS fonctionne et db résout vers l’IP du conteneur attendu.

Décision : Si cela ne résout pas, vérifiez que les deux conteneurs sont sur le même réseau et que vous utilisez le bon nom de service.

Task 15: Show which networks a container is attached to (avoid guessing)

cr0x@server:~$ docker inspect -f '{{range $k,$v := .NetworkSettings.Networks}}{{$k}} {{end}}' app-api-1
app_default 

Ce que cela signifie : Le conteneur est attaché à app_default.

Décision : Si un conteneur est attaché à un réseau différent de celui attendu (comme bridge), corrigez le fichier Compose ou recréez le conteneur.

Task 16: Detect orphaned endpoints and “in use” networks before removal

cr0x@server:~$ docker network inspect -f 'Containers={{len .Containers}}' app_default
Containers=3

Ce que cela signifie : Trois points de terminaison conteneur sont attachés. Si vous essayez de supprimer ce réseau, Docker refusera sauf si vous déconnectez ou supprimez les conteneurs.

Décision : Si vous devez reconstruire le réseau, planifiez un arrêt/recréation contrôlé de la stack.

Task 17: Safely stop a project and remove only its network

cr0x@server:~$ cd /srv/app
cr0x@server:/srv/app$ docker compose -p app down
[+] Running 4/4
 ✔ Container app-web-1  Removed
 ✔ Container app-api-1  Removed
 ✔ Container app-db-1   Removed
 ✔ Network app_default  Removed

Ce que cela signifie : Les conteneurs du projet et son réseau par défaut sont supprimés. Les volumes restent à moins d’utiliser -v.

Décision : C’est la méthode de reconstruction sûre lorsque le réseau est corrompu ou mal configuré. Ensuite : docker compose up -d pour recréer.

Task 18: Confirm iptables/nftables hasn’t been silently neutered

cr0x@server:~$ sudo iptables -S DOCKER | head -n 5
-N DOCKER
-A DOCKER -i docker0 -j RETURN
-A DOCKER ! -i docker0 -p tcp -m tcp --dport 5432 -j DNAT --to-destination 172.22.0.2:5432

Ce que cela signifie : Les chaînes iptables de Docker existent. Si la chaîne DOCKER est manquante ou vide sur un hôte qui compte sur des ports publiés, la connectivité échouera même si le réseau existe.

Décision : Si les chaînes sont manquantes après un redémarrage du démon, vérifiez la config du démon, le gestionnaire de pare-feu, et si l’hôte utilise le backend nftables avec des règles incompatibles.

Blague #1 : Si vous réparez le réseau Docker en rebootant, vous ne l’avez pas réparé—vous avez relancé la roulette et gagné cette fois.

Comment reconstruire les réseaux sans tout casser

Principe 1 : Préférez recréer les réseaux via l’outil qui les a créés

Si Compose a créé le réseau, laissez Compose le recréer. Compose applique des labels et des conventions de nommage qui rendent les opérations futures prévisibles. docker network create en manuel convient pour des expérimentations ponctuelles ; en production, c’est souvent la source de mystères.

Principe 2 : Contenez le rayon d’impact

Il y a trois niveaux d’intervention :

• Périmètre projet : Recréez app_default et les conteneurs du projet seulement.
• Périmètre hôte : Réparez les réseaux par défaut (bridge/docker0) et la programmation iptables. Plus risqué.
• Réinitialisation de l’état du démon : Dernier recours ; peut détruire tout l’état Docker sur l’hôte.

Reconstruction au périmètre projet : la correction la plus sûre et la plus courante

Si vous obtenez « network not found » pour un réseau géré par Compose, procédez ainsi :

1. Confirmez le nom du réseau attendu par Compose (souvent <project>_default).
2. Exécutez docker compose up -d dans le bon répertoire et avec le bon nom de projet. Cela devrait recréer le réseau s’il est manquant.
3. Si des conteneurs sont bloqués ou à moitié créés, faites docker compose down puis up -d.

Quand docker compose up -d ne le corrige-t-il pas ? Quand vous avez des ressources obsolètes avec des noms en conflit, des noms de projet incohérents, ou des réseaux externes référencés qui ne sont pas créés.

Réseaux externes : où les humains se tendent des pièges

Compose supporte external: true. Cela signifie « Compose ne créera pas ce réseau ». Si le réseau manque, Compose échouera—et correctement. C’est le scénario où les opérateurs jureront que Compose est cassé. Il ne l’est pas. Vous lui avez dit de ne pas créer le réseau.

Si votre stack utilise des réseaux externes, votre tâche est de vous assurer qu’ils existent et ont une configuration stable (subnet, driver) entre les reconstructions d’hôte. Si vous ne pouvez pas garantir cela, cessez d’utiliser des réseaux externes sauf nécessité réelle.

Recréation manuelle (uniquement si nécessaire)

Parfois vous ne pouvez pas exécuter Compose (CI en panne, dépôt indisponible, ou vous avez besoin d’un pont temporaire pour remettre des services critiques). Dans ce cas, recréez manuellement avec précaution :

• Faites correspondre le driver (bridge, overlay, macvlan).
• Faites correspondre les paramètres IPAM si quelque chose dépend de plages fixes.
• Sachez que les labels et la propriété Compose ne seront pas présents, ce qui affectera docker compose down plus tard.

cr0x@server:~$ docker network create --driver bridge --subnet 172.22.0.0/16 app_default
b9a1f1a2a3c4d5e6f7a8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8

Ce que cela signifie : Vous avez créé un réseau bridge avec un subnet fixe.

Décision : N’utilisez ceci que comme solution provisoire. Une fois stable, revenez à la création gérée par Compose pour éviter la dérive.

Reconstruire le bridge par défaut (docker0) sans chaos

Si l’erreur concerne le réseau bridge ou que docker0 est manquant/cassé, vous êtes en périmètre hôte. Symptômes : les conteneurs échouent à démarrer malgré le réseau par défaut, ou les ports publiés cessent de fonctionner après des upgrades.

Procédez comme un adulte :

• Planifiez une fenêtre si cet hôte exécute quoi que ce soit d’important.
• Arrêtez proprement les charges de travail (Compose down, Swarm drain, selon le cas).
• Redémarrez Docker et validez docker0, les routes et les chaînes iptables.

cr0x@server:~$ ip link show docker0
3: docker0: <NO-CARRIER,BROADCAST,MULTICAST,UP> mtu 1500 qdisc noqueue state DOWN mode DEFAULT group default
    link/ether 02:42:8f:aa:bb:cc brd ff:ff:ff:ff:ff:ff

Ce que cela signifie : L’interface existe. L’état DOWN est normal si aucun conteneur n’est attaché.

Décision : Si docker0 n’existe pas, suspectez une configuration du démon désactivant la création du bridge, ou un répertoire d’état corrompu.

Réinitialisation de l’état du démon : dernier recours, couteau très tranchant

Si les réseaux disparaissent régulièrement, ou si Docker refuse d’en créer de nouveaux, vous pouvez avoir une corruption du répertoire /var/lib/docker (ou des problèmes de driver de stockage). La correction peut consister à effacer l’état Docker et redéployer les charges depuis la source de vérité. Ce n’est pas « reconstruire le réseau ». C’est « reconstruire le nœud ».

N’improvisez pas cela sur un serveur « pet » qui contient la seule copie de vos volumes. Si vous n’êtes pas sûr, arrêtez-vous et inventairez les données présentes.

Blague #2 : « docker system prune -a » n’est pas un plan de maintenance ; c’est un test de personnalité.

Trois mini-histoires du monde de l’entreprise (douleur incluse)

Mini-histoire 1 : L’incident causé par une mauvaise hypothèse

Une entreprise de taille moyenne exécutait quelques applications internes sur une seule VM musclée. L’équipe utilisait Docker Compose, et ça fonctionnait suffisamment bien pour que personne ne touche la section réseau pendant des mois. Puis un ingénieur a ajouté un external: true parce qu’il voulait que deux projets Compose partagent un réseau de reverse proxy.

Ils ont supposé que « external » signifiait « partagé entre projets » et que Compose le recréerait s’il manquait. Ils ont déployé une nouvelle VM depuis une image, lancé docker compose up -d, et l’ont vu échouer immédiatement : « network proxy_net not found. » L’astreinte a fait ce que font les astreintes : réessayer, redémarrer Docker, réessayer encore.

La panne n’était pas l’erreur elle-même ; c’était la réponse. Sous pression, ils ont créé le réseau manuellement—mais avec un subnet différent de l’ancien hôte. Le reverse proxy est remonté, mais des allowlists internes et quelques contrôles de monitoring codés en dur s’attendaient à l’ancienne plage. La moitié du trafic était maintenant « mystérieusement » bloquée par une règle de pare-feu destinée à protéger une base de données.

La correction a été simple et pédagogiquement agaçante : créer explicitement le réseau externe et pinner son subnet dans le code d’infrastructure, pas dans la mémoire de quelqu’un. Ensuite reconstruire l’hôte de façon contrôlée pour que la configuration réseau ne dépende pas de qui a tapé quoi au clavier.

Mini-histoire 2 : L’optimisation qui s’est retournée contre eux

Une autre organisation voulait « accélérer les déploiements » et réduire l’usage disque. Quelqu’un a ajouté un job de nettoyage nocturne qui lançait une commande prune pour supprimer les objets Docker inutilisés. Cela a libéré de l’espace—jusqu’à ce que ça ne le fasse plus.

Le job s’est exécuté pendant une période calme où une stack Compose était en cours de redéploiement. Pour une courte fenêtre, des conteneurs étaient arrêtés et des réseaux paraissaient « inutilisés ». Le prune a supprimé un réseau bridge défini par l’utilisateur qui allait être réutilisé quelques secondes après. Le déploiement a repris, et les conteneurs ont échoué au démarrage : « network not found. » L’alerte était retardée parce que les checks ne tournaient que toutes les quelques minutes. Super timing.

Ils ont « corrigé » en relançant le déploiement, qui a recréé le réseau. Mais le vrai problème était que le job prune restait. Des semaines plus tard, le même motif est revenu, cette fois pendant une fenêtre de changement plus chargée. Le second incident a été plus long car les ingénieurs chassaient des fantômes iptables et des problèmes DNS qui n’étaient pas la cause.

La correction finale a été banale : exécuter prune seulement avec des filtres explicites, jamais sur des hôtes partagés, et ne jamais le faire sans vérifier les déploiements en cours. Ils ont aussi déplacé des charges vers un système avec des nœuds éphémères rendant le nettoyage sans importance. La vitesse s’est améliorée. Pas parce que prune était malin, mais parce que la plateforme n’était plus fragile.

Mini-histoire 3 : La pratique ennuyeuse mais correcte qui a sauvé la mise

Une équipe proche de la finance avait une règle : chaque projet Compose doit déclarer ses réseaux avec des noms explicites et des plages IPAM, et chaque réseau externe doit être créé par une étape de provisioning avant tout déploiement d’application. La règle agaçait les développeurs, ce qui est souvent un signe qu’elle rend service.

Un jour un hôte a perdu l’état Docker après un incident disque. Les réseaux avaient disparu. Les conteneurs étaient partis. Tout le monde a passé une mauvaise après-midi. Mais le runbook de redéploiement n’impliquait pas de conjectures : provisionner les réseaux externes, déployer les stacks Compose, vérifier la connectivité. Parce que les subnets étaient pinners, les règles de pare-feu et le monitoring n’ont pas nécessité d’éditions d’urgence.

La récupération n’a rien eu de magique ; elle a été prévisible. Leur runbook incluait aussi « vérifiez que vous êtes dans le bon contexte Docker » et « joignez docker info et journalctl à l’incident ». Moins de folklore, plus de preuves.

Ils ont quand même eu un incident. Ils n’ont juste pas eu un second incident auto-infligé par-dessus. En exploitation, ça ressemble à une victoire.

Erreurs fréquentes : symptôme → cause → correction

1) Symptom: “network <hex> not found” after moving a Compose project directory

Cause : Le nom du projet a changé, les anciennes ressources référencées par ID n’existent plus, ou vous invoquez Compose avec une valeur -p différente.

Correction : Lancez Compose avec le nom de projet original si vous voulez réutiliser les ressources, ou exécutez docker compose -p <name> down (si possible) puis redéployez avec le nouveau nom de façon cohérente.

2) Symptom: Compose fails only on a network marked external

Cause : Le réseau externe n’est pas créé (par conception, Compose ne le créera pas).

Correction : Créez-le explicitement (idéalement via du provisioning/automation), et pinner le subnet/driver pour correspondre aux attentes.

3) Symptom: “network not found” appears after a cleanup job or disk pressure event

Cause : Un prune automatisé a supprimé des réseaux, ou l’état Docker a été partiellement perdu suite à un disque plein/corruption.

Correction : Supprimez/limitez les jobs de nettoyage ; reconstruisez les réseaux via Compose ; enquêtez sur la santé du stockage hôte et la durabilité de l’état Docker.

4) Symptom: Network exists, but new containers cannot attach; errors mention sandbox/join

Cause : Endpoints obsolètes, paires veth restantes, ou incohérence interne du démon/libnetwork après des crashs.

Correction : Redémarrage contrôlé du projet (compose down/up). Si persistant entre projets, redémarrez Docker pendant une fenêtre ; si toujours cassé, planifiez une reconstruction du nœud.

5) Symptom: Published ports stop working, but no “network not found”

Cause : La programmation iptables/nftables est cassée ; le gestionnaire de pare-feu a écrasé les chaînes Docker.

Correction : Corrigez l’intégration du pare-feu ; redémarrez Docker après correction ; validez les chaînes DOCKER et les règles NAT.

6) Symptom: You can’t see the network, but coworkers can

Cause : Mauvais contexte Docker, mauvais hôte, ou session SSH vers le mauvais environnement.

Correction : Vérifiez le contexte et le endpoint ; standardisez les prompts de shell ; exigez des indicateurs d’environnement explicites dans les runbooks.

Listes de contrôle / plans pas à pas

Checklist A: Single Compose stack fails with “network not found”

1. Confirmez le contexte Docker et l’identité de l’hôte (évitez de déboguer la mauvaise machine).
2. Ne prunez rien. D’abord, collectez des preuves :
   • docker network ls
   • docker compose -p <proj> ps
   • sudo journalctl -u docker --since "1 hour ago"
3. Si le réseau manquant est le réseau par défaut du projet : exécutez docker compose up -d depuis le bon répertoire.
4. Si ça échoue encore : faites docker compose down (sans volumes) puis docker compose up -d.
5. Validez : docker network inspect (driver/subnet), docker exec ... getent hosts ....
6. Si ça se reproduit : trouvez et tuez le processus qui supprime les réseaux (job de nettoyage, habitude humaine, agent CI).

Checklist B: Multiple projects affected or default networks are missing

1. Supposez un problème au niveau hôte jusqu’à preuve du contraire.
2. Vérifiez les logs du démon pour des erreurs de stockage/état ; vérifiez l’espace disque libre et la santé du système de fichiers.
3. Planifiez une fenêtre de maintenance (oui, même si c’est « juste le réseau »).
4. Arrêtez proprement les charges de travail.
5. Redémarrez Docker ; confirmez que docker0 existe et que les chaînes iptables sont présentes.
6. Si l’état est clairement corrompu : reconstruisez le nœud depuis la source de vérité plutôt que d’éditer à la main /var/lib/docker.

Checklist C: External network strategy that doesn’t bite you later

1. N’utilisez les réseaux externes que lorsque vous avez vraiment besoin d’une connectivité inter-projets.
2. Créez-les dans du code de provisioning, pas dans l’historique du terminal d’un humain.
3. Pinner le subnet et le driver et documentez la raison.
4. Validez avec un conteneur jetable : attachez-le, résolvez les noms, atteignez les ports attendus.
5. Auditez les jobs de nettoyage : les réseaux externes ne doivent jamais être prunés automatiquement sur des hôtes partagés.

FAQ

1) Pourquoi Docker se plaint d’un ID de réseau plutôt que d’un nom ?

Parce qu’en interne Docker référence les réseaux par ID. Les noms sont pour les humains. Les stacks et conteneurs stockent souvent l’ID, donc quand l’ID disparaît vous obtenez un indice en forme d’hexadécimal.

2) Puis-je simplement recréer un réseau avec le même nom et en finir ?

Parfois. Mais si un conteneur référence l’ancien ID de réseau, recréer par nom ne suffira pas tant que le conteneur n’est pas recréé ou réattaché. L’approche la plus sûre est de laisser Compose recréer à la fois le réseau et les conteneurs affectés.

3) Est-ce que docker compose up -d recrée automatiquement les réseaux manquants ?

Oui pour les réseaux qu’il gère (non externes). Si le réseau est marqué external: true, Compose ne le créera pas et échouera s’il manque.

4) Quelle est la façon la plus sûre de reconstruire un réseau Compose cassé ?

docker compose down (sans -v sauf si vous le souhaitez), puis docker compose up -d. Cela supprime les conteneurs et le réseau de projet et recrée proprement.

5) La suppression d’un réseau supprimera-t-elle mes données ?

La suppression d’un réseau ne supprime pas les volumes. Mais si vos données vivent dans le système de fichiers du conteneur (sans volume), la suppression des conteneurs les supprime. Inventoriez vos volumes avant de « nettoyer ».

6) Comment savoir si un job de nettoyage a causé ça ?

Vérifiez les timers systemd/cron, les scripts CI, et les historiques de shell. Regardez aussi les timestamps des logs du démon : un « network removed » soudain ou un trou suivi de réseaux manquants est un fort indice.

7) « network not found » peut-il provenir d’iptables ou de règles de pare-feu ?

Typiquement non. Les problèmes de pare-feu causent des problèmes de connectivité, pas des erreurs d’objet manquant. Si le démon dit « not found », il ne trouve pas l’objet réseau dans son état.

8) Et si c’est Swarm et des réseaux overlay ?

Alors vous devez confirmer la santé du cluster Swarm. Les réseaux overlay dépendent de l’état des managers. Un nœud sorti du cluster ou un quorum de managers cassé peut provoquer des échecs d’attachement réseau. Corrigez l’état du cluster d’abord, puis redéployez les services.

9) Comment prévenir que ça ne se reproduise ?

Arrêtez d’exécuter des prune agressifs sur des hôtes partagés, pinner la configuration réseau quand la stabilité compte, et traitez /var/lib/docker comme un état persistant qui nécessite de la bonne hygiène disque et une surveillance.

Prochaines étapes à faire réellement

Quand Docker dit « network not found », croyez-le. Ne perdez pas de temps à déboguer des paquets pour un objet réseau qui n’existe pas.

1. Faites le diagnostic rapide : confirmez le contexte, confirmez que le réseau manque, vérifiez les logs du démon.
2. Corrigez à la plus petite échelle : recréez via Compose pour ce projet uniquement ; évitez les réinitialisations hôte-entière.
3. Si cela se répète, traitez-le comme un problème système : jobs de nettoyage, santé du disque, stabilité de l’état du démon, et provisionnement reproductible des réseaux externes.
4. Rédigez le runbook que vous auriez aimé avoir aujourd’hui : commandes pour vérifier l’état, et la séquence exacte « down/up » qui est sûre pour votre stack.

Reconstruire des réseaux sans tout casser n’est pas une question d’exploits héroïques. C’est une question de savoir quelle couche est cassée et de refuser d’« optimiser » jusqu’à provoquer de nouveaux incidents.