Docker Compose : retrouver l’erreur utile dans les logs d’un conteneur

Quand un conteneur Docker Compose ne démarre plus correctement, le message utile se trouve rarement dans la page d’accueil ou dans l’état général du projet. Il faut cibler le service concerné, lire les dernières lignes et reproduire l’erreur avec les horodatages visibles. Voici une méthode courte pour éviter de se noyer dans tous les logs.

Commencez par identifier le service

Depuis le dossier qui contient votre fichier compose.yaml ou docker-compose.yml, listez les services et leur état :

docker compose ps

docker compose ps -a

La première commande montre les conteneurs actifs. Avec -a, vous voyez aussi ceux qui se sont arrêtés. C’est important pour distinguer un service qui tourne mais répond mal d’un conteneur qui quitte immédiatement après son démarrage.

Pour afficher les logs d’un seul service, utilisez son nom déclaré dans le fichier Compose :

docker compose logs web

Remplacez web par le service réellement listé par docker compose config --services. Cette commande évite de chercher le nom généré du conteneur à la main.

Limiter la sortie avant de suivre le problème

Un service ancien peut avoir accumulé des milliers de lignes. Commencez par un extrait récent :

docker compose logs --tail=100 web
docker compose logs --since=30m web
docker compose logs --since="2026-08-10T08:30:00" web

--tail limite le nombre de lignes et --since filtre une période. Vous pouvez aussi demander les horodatages :

docker compose logs --timestamps --tail=100 web

Les timestamps permettent de comparer l’erreur avec un redémarrage, une modification de configuration ou un appel vers un service voisin. Sans eux, plusieurs tentatives peuvent donner l’impression d’être un seul incident.

Suivre les logs pendant la reproduction

Pour voir apparaître l’erreur au moment où elle se produit, ajoutez --follow :

docker compose logs --follow --timestamps --tail=50 web

Dans un autre terminal, reproduisez l’action qui pose problème : ouverture d’une page, appel API, tâche planifiée ou redémarrage du service. Arrêtez le suivi avec Ctrl + C. Cette interruption ne stoppe pas le conteneur, elle ferme seulement l’affichage des logs.

Pour suivre plusieurs services, indiquez-les explicitement :

docker compose logs --follow --timestamps --tail=50 web db

Gardez cette liste courte. Afficher toute la stack rend souvent l’ordre des messages illisible, surtout quand un proxy, une application et une base de données écrivent en même temps.

Ne confondez pas logs, état et disque plein

Un message dans les logs ne suffit pas toujours à expliquer l’incident. Vérifiez aussi l’état du conteneur et sa raison d’arrêt :

docker compose ps -a
docker inspect --format='{{.State.Status}} {{.State.ExitCode}} {{.State.Error}}' $(docker compose ps -aq web)

Un code de sortie non nul, une boucle de redémarrage ou une erreur de montage ne se traitent pas comme une simple erreur applicative. Si le service écrit beaucoup, contrôlez également l’espace disponible sur l’hôte :

df -h
docker system df

Un disque plein peut empêcher l’écriture des logs, la création d’un fichier temporaire ou le démarrage d’une base. Ne supprimez pas des volumes ou des images au hasard. Identifiez d’abord ce qui occupe l’espace et vérifiez que les données utiles sont sauvegardées.

La documentation officielle de docker compose logs détaille les options disponibles. Pour l’installation et la gestion du moteur sur Debian, vous pouvez aussi consulter notre guide sur Docker sous Debian. Quand le service est piloté par systemd plutôt que par Compose, les commandes de journalctl sous Linux sont généralement plus adaptées.

Avec un service ciblé, une fenêtre temporelle courte et une reproduction horodatée, vous obtenez rapidement l’erreur à corriger au lieu d’un mur de logs impossible à exploiter.