Erreurs Docker courantes et correctifs avec exemples pratiques : guide d'implémentation

Introduction

Les messages d'erreur Docker peuvent sembler cryptiques, mais la plupart reviennent à quelques causes répétitives. Ce guide cartographie les erreurs les plus fréquentes vers leurs causes racines, vous donne des commandes exactes pour les diagnostiquer, et propose des correctifs sûrs que vous pouvez vérifier en local avant un déploiement plus large. Il s'adresse aux développeurs et équipes DevOps qui veulent standardiser leur troubleshooting et gagner en fiabilité.

Mots-clés utiles conservés pour la recherche: Docker common errors, Docker fixes, Docker error messages, Docker debugging, Docker troubleshooting.

Vue d'ensemble du workflow

Utilisez ce flux pour réduire le bruit et éviter les itérations inutiles.

1. Reproduire exactement

• Capturez la commande et les versions:
• docker --version
• docker compose version
• docker info (masquez les secrets)
• Relancez avec des logs complets:
• docker build --progress=plain .
• docker run --rm -it image: tag command

1. Lire tout le message d'erreur

• Beaucoup d'erreurs Docker affichent un résumé court, suivi de la vraie cause quelques lignes plus haut. Remontez dans les logs.

1. Minimiser le scénario

• Remplacez votre app par une repro minuscule:
• Utilisez un Dockerfile de 5 lignes et un seul COPY ou RUN pour isoler l'étape fautive.

1. Différencier la configuration

• Inspectez le Dockerfile étape par étape.
• Vérifiez les overrides Compose et les fichiers d'env.
• Comparez tags, plateformes et montages entre un cas OK et KO.

1. Appliquer le plus petit correctif sûr

• Modifiez la configuration avant le code si le problème touche chemins, permissions ou plateforme.

1. Vérifier en local

• Testez dans un environnement propre:
• docker system prune -f (optionnel, attention cela supprime les ressources inutilisées)
• docker build --no-cache .
• docker run --rm image: tag

Erreurs de build courantes

1) COPY failed: file not found in build context

Symptômes:

• Exemple: COPY failed: file not found in build context or excluded by .dockerignore

Pourquoi cela arrive:

• Le chemin visé est hors du contexte de build (le chemin passé à docker build).
• .dockerignore exclut le fichier.

Correctif:

• Construisez depuis le bon répertoire de contexte et ajustez les chemins.
• Mettez à jour .dockerignore pour conserver les fichiers nécessaires.

Exemple:

# Faux (build depuis le parent, mais attente des fichiers app/)
docker build -t myapp .

# Correct : build avec app/ en contexte
docker build -t myapp ./app

# Passez en revue .dockerignore et retirez les motifs qui masquent les fichiers requis

2) exec format error (mauvaise architecture)

Symptômes:

• standard_init_linux.go... exec format error
• L'image fonctionne sur une machine mais pas sur une autre (ex. laptop ARM vs serveur AMD64)

Pourquoi cela arrive:

• La plateforme de l'image diffère de l'hôte ou du nœud cible.

Correctif:

• Construisez ou tirez pour la bonne plateforme.

Exemples:

# Forcer la plateforme au build ou au run
DOCKER_BUILDKIT=1 docker build --platform=linux/amd64 -t myapp: amd64 .
docker run --rm --platform=linux/amd64 myapp: amd64

# Ou utilisez une base multi-arch (ex. python:3.11-slim) et laissez BuildKit produire une image adaptée

3) no space left on device

Symptômes:

• Le build échoue lors de l'écriture des couches ou pendant apt-get install.

Pourquoi cela arrive:

• Les données Docker locales (images, couches, cache de build) saturent le disque.

Correctif:

# Voir l'usage disque
docker system df

# Supprimer les données en suspens/inutilisées (attention : libère globalement)
docker system prune -f
# Supprimer aussi images et volumes inutilisés si c'est sans risque
docker image prune -a -f
docker volume prune -f

4) RUN échoue à cause du shell ou des fins de ligne

Symptômes:

• /bin/sh: 1: script.sh: not found
• exec user process caused: no such file or directory

Pourquoi cela arrive:

• Fins de ligne Windows CRLF dans les scripts.
• Bit exécutable manquant ou mauvais shebang.

Correctif:

# Normaliser en LF au commit
git config core.autocrlf input

# Ou convertir les fichiers
apt-get update && apt-get install -y dos2unix && dos2unix script.sh

# Assurer l'exécutable et un shebang valide
chmod +x script.sh
sed -n '1p' script.sh  # doit commencer par #!/bin/sh ou #!/usr/bin/env bash

5) Confusion liée au cache de build

Symptômes:

• Anciennes dépendances présentes ; vos changements ne s'appliquent pas.

Correctif:

# Afficher chaque étape en détail
DOCKER_BUILDKIT=1 docker build --progress=plain .

# Court-circuiter le cache si nécessaire
docker build --no-cache .

Erreurs au run et avec Compose

1) Port is already allocated

Symptômes:

• Error starting userland proxy: listen tcp 0.0.0.0:80: bind: address already in use

Correctif:

# Trouver le processus en conflit (Linux/macOS)
lsof -i :80
# Windows (PowerShell)
Get-NetTCPConnection -LocalPort 80 | Format-List

# Arrêter ou remapper le port
# docker run -p HOST:CONTAINER
docker run -p 8080:80 nginx: alpine

# Dans compose.yml
services:
  web:
    image: nginx: alpine
    ports:
      - "8080:80"

2) exec user process caused: no such file or directory

Symptômes:

• Survient immédiatement au démarrage du conteneur.

Pourquoi cela arrive:

• ENTRYPOINT ou CMD pointe vers un fichier inexistant ou avec des fins de ligne CRLF.

Correctif:

# Inspecter l'image
docker run --rm -it --entrypoint sh myapp: tag -c 'ls -l /app && file /app/entrypoint.sh'

# Normaliser fins de ligne et permissions comme dans les fixes de build

3) OCI runtime create failed: permission denied

Pourquoi cela arrive:

• Permissions des volumes montés, limitations en Docker rootless, ou refus SELinux sur Linux.

Correctif:

# Sur hôtes avec SELinux, étiquetez les bind mounts
# :z pour partagé, :Z pour étiquetage privé
-v /host/data:/data: Z

# Aligner l'utilisateur conteneur avec les fichiers hôte
# Exemple : exécuter avec l'UID 1000 de l'hôte et chown sur le volume
docker run -u 1000:1000 -v $PWD/data:/data myapp: tag

4) Réseau introuvable dans Compose

Symptômes:

• network mynet declared as external, but could not be found

Correctif:

# Créer le réseau ou le rendre interne au projet
docker network create mynet
# Ou retirer external: true et laisser Compose le créer

Réseau et erreurs DNS

1) Temporary failure in name resolution

Symptômes:

• La résolution DNS échoue dans le conteneur.

Pourquoi cela arrive:

• DNS de l'hôte injoignable, proxy d'entreprise, ou sortie bloquée.

Correctif:

# Tester le DNS dans un conteneur
docker run --rm busybox nslookup google.com || true

# Forcer un DNS explicite pour le conteneur
docker run --rm --dns 8.8.8.8 busybox nslookup google.com

# Configurer un DNS au niveau du démon (daemon.json), puis redémarrer Docker
{
  "dns": ["8.8.8.8", "1.1.1.1"]
}

Si vous êtes derrière un proxy, définissez HTTP_PROXY/HTTPS_PROXY/NO_PROXY dans le Dockerfile (au build) et dans l'environnement d'exécution au besoin.

2) Cannot pull: lookup registry-1.docker.io: no such host

Correctif:

• Appliquez les mêmes étapes DNS ci‑dessus.
• Vérifiez que vous pouvez curl https://registry-1.docker.io depuis l'hôte.

Volumes et erreurs de permissions

1) Permission denied sur les bind mounts

Symptômes:

• L'application ne peut pas lire/écrire les fichiers montés.

Pourquoi cela arrive:

• Décalage d'UID/GID entre l'hôte et l'utilisateur conteneur.
• Étiquettes SELinux bloquant l'accès.

Correctif:

# Aligner UID/GID ou utiliser un utilisateur compatible
docker run -u $(id -u):$(id -g) -v $PWD/data:/data myapp: tag

# Sur hôtes SELinux
docker run -v $PWD/data:/data: Z myapp: tag

# Préférer les volumes nommés pour des écritures portables
volumes:
  data:
services:
  app:
    volumes:
      - data:/data

2) Partage de fichiers non activé (macOS/Windows)

Symptômes:

• Le montage échoue ou le répertoire est vide dans le conteneur.

Correctif:

• Activez le partage de fichiers pour le lecteur/dossier dans les réglages de Docker Desktop.

Images et erreurs de registre

1) pull access denied, repository does not exist or may require authorization

Correctif:

# Vérifier le nom exact de l'image et le tag
docker pull registry.example.com/team/app:1.2.3

# Se connecter au registre
docker login registry.example.com

2) manifest unknown or not found

Pourquoi cela arrive:

• Le tag n'existe pas ou le manifest pour votre plateforme est manquant.

Correctif:

# Listez les tags disponibles (si l'UI ou l'API de votre registre le permet). Sinon, confirmez le tag dans votre processus de release.
# Tirez avec une plateforme explicite si un manifest multi-arch existe
docker pull --platform linux/amd64 image: tag

3) Rate limit exceeded (registres publics)

Correctif:

• Authentifiez-vous pour augmenter les limites.
• Utilisez un miroir ou un cache privé de registre si possible.

Performance et ressources

1) OOMKilled ou pression mémoire

Symptômes:

• Le conteneur quitte brutalement ; les logs indiquent OOMKilled.

Correctif:

# Contraindre et observer
# Exemple Compose v2
services:
  app:
    image: myapp: tag
    deploy:
      resources:
        limits:
          memory: 512M
# Ou via docker run
docker run --memory=512m myapp: tag

Ajustez l'usage mémoire de l'app ou relevez les limites selon les besoins.

2) Builds lents dus à des ratés de cache

Correctif:

• Réordonnez le Dockerfile pour placer les étapes les plus stables (installation des paquets OS) avant le COPY du code applicatif, afin de maximiser la réutilisation du cache.

Plan pilote local

Démarrez avec un pilote étroit, mesurable, qui tourne entièrement sur un laptop développeur et reste facile à inspecter.

Objectif

• Prouver que les erreurs courantes sont détectées et corrigées rapidement sur un seul service.

Périmètre

• Un Dockerfile (p. ex. un Nginx ou Python minimal).
• Un compose.yml exposant un port HTTP et un répertoire de données inscriptible.

Étapes

1. Créer un mini-service

# Dockerfile
FROM nginx: alpine
COPY ./public /usr/share/nginx/html

1. Ajouter des vérifications de pannes courantes

• Supprimez un fichier de public et observez l'échec de COPY ; corrigez via le contexte et .dockerignore.
• Introduisez des fins de ligne CRLF dans un script d'entrée ; corrigez avec LF et chmod +x.
• Forcez un décalage de plateforme ; exécutez avec --platform pour valider le comportement.
• Montez un répertoire de données ; testez les permissions via les UID et, avec SELinux, :Z.

1. Instrumenter un diagnostic rapide

# Makefile (optionnel)
run:
	docker compose up --build
shell:
	docker run --rm -it --entrypoint sh myapp: dev
clean:
	docker system prune -f

1. Documenter les correctifs exacts qui ont fonctionné

• Conservez un court troubleshooting.md avec texte d'erreur, cause et commande utilisée.

1. Étendre progressivement

• Ajoutez un second service (p. ex. API) et un réseau défini par l'utilisateur.
• Ajoutez des pulls d'images depuis un registre privé pour valider l'authentification et la gestion des tags.

Ce pilote est petit, mesurable et simple à inspecter localement. C'est une voie sûre pour standardiser l'approche avant d'étendre à Docker Compose, Kubernetes ou votre CI/CD (ex. GitLab CI/CD).

Conclusion

La plupart des problèmes Docker se répètent : erreurs de chemin et de contexte, décalages de plateforme, subtilités DNS/proxy, et permissions sur les montages. Avec un workflow simple et réutilisable, plus les correctifs ci‑dessus, vous pouvez les résoudre vite et en sécurité. Commencez avec le pilote local, consignez ce qui marche, puis étendez ces mêmes schémas à Docker Compose, Kubernetes et votre système CI.