Docker : résolution des problèmes courants
Un conteneur redémarre en boucle, un port est utilisé, plus d'espace disponible, « permission denied », un service ne voit pas son voisin — un tableau des symptômes et une procédure de diagnostic.
Mis à jour le 23 août 2026
La quasi-totalité des problèmes de conteneurs se résument à une douzaine de cas courants. Le diagnostic commence toujours par les trois mêmes commandes.
Les trois premières commandes
docker compose ps
docker compose logs --tail 100 <service>
docker inspect -f '{{.State.Status}} {{.State.ExitCode}} {{.State.OOMKilled}} {{.State.Error}}' <container>
Le statut, les dernières lignes du journal et le code de sortie répondent à la plupart des questions. Ensuite, partez du symptôme.
Tableau des symptômes
| Symptôme | Cause probable | Que faire |
|---|---|---|
Restarting en permanence | L'application plante au démarrage | docker compose logs --tail 200, lisez la première erreur, pas la dernière |
Code de sortie 137, OOMKilled: true | Mémoire insuffisante | Augmentez la limite ou trouvez la fuite, voir limites de ressources |
| Code de sortie 1 immédiatement après le démarrage | Erreur dans la configuration ou les variables | docker compose config — vérifiez les substitutions |
port is already allocated | Le port est occupé par un autre processus | sudo ss -tulpn | grep :<port> |
no space left on device | Espace disque ou inodes épuisés | df -h et df -i, voir espace disque |
permission denied sur un fichier de volume | Incohérence d'UID | docker compose exec app id, puis chown ou PUID/PGID |
| L'application ne voit pas la base de données | Réseaux différents ou requête vers localhost | Voir réseaux Docker |
Cannot connect to the Docker daemon | Le service n'est pas démarré ou vous manquez de permissions | sudo systemctl status docker, le groupe docker |
| Tout est lent, la charge est faible | Goulot d'étranglement du disque | iostat -x 2, voir vitesse du disque |
Le conteneur plante, mais le journal est vide
Cela se produit lorsque le processus meurt avant de pouvoir afficher quoi que ce soit. Lancez l'image manuellement avec un shell au lieu de la commande principale :
docker run --rm -it --entrypoint sh <image>
À l'intérieur, exécutez la commande de démarrage à la main — l'erreur apparaîtra à l'écran. Pendant que vous y êtes, vérifiez si les fichiers de configuration sont en place :
docker compose run --rm app cat /app/config.yaml
Les modifications ne sont pas appliquées
Le classique : vous modifiez un fichier, vous redémarrez, et rien ne change.
docker compose config # does Compose see your changes
docker compose up -d --force-recreate app
docker compose exec app cat /etc/app/config.yaml
Il y a généralement deux causes : le fichier est monté ailleurs que là où vous le croyez, ou le conteneur voit une copie intégrée à l'image lors du build.
Ne corrigez pas le problème avec
docker system prune -a. Cette commande supprime les images, les réseaux et le cache de build inutilisés, et avec l'option--volumes, les volumes contenant des données également. Un volume devient « inutilisé » dès que son conteneur est arrêté. Identifiez d'abord la cause, puis nettoyez.
Quand nettoyer, finalement
docker system df
docker image prune
docker builder prune
docker container prune
docker system df montrera ce qui occupe exactement l'espace : images, cache de build, volumes ou journaux de conteneurs. C'est généralement le cache de build qui est en cause — le supprimer est sans danger.
Si la machine ne répond plus
SSH ne se connecte pas, le site ne s'ouvre pas — généralement un conteneur a épuisé la mémoire et le système est passé en swap. Connectez-vous via la console du panneau de la machine. Pour htop et btop, il vous faut le mode « Screen » : la taille de la fenêtre n'est pas transmise sur une ligne de texte, elle est donc toujours de 80×24.
free -h
sudo dmesg -T | tail -40
sudo systemctl restart docker
Si le système ne démarre pas du tout, basculez le mode de démarrage sur le disque de récupération SystemRescue dans l'onglet « Accès » : la machine redémarrera dessus, connexion root sans mot de passe, et le disque sera visible sous /dev/sda. De là, vous pouvez monter la partition et récupérer les données.
Ce qu'il faut vérifier avant, pas après
- Les limites de taille des journaux sont définies — voir journaux de conteneurs.
- Les limites de mémoire sont définies pour tous les services.
- Les versions des images sont figées, et l'ancienne image n'a pas été supprimée — voir mises à jour des conteneurs.
- Une copie des données existe et a été vérifiée — voir test de restauration.