Ce guide rassemble, sous forme de questions, les erreurs les plus fréquemment rencontrées en apprenant Docker. Beaucoup ont déjà été évoquées ponctuellement dans les guides précédents ; les retrouver toutes au même endroit facilite le diagnostic le jour où l'une d'elles survient sur un vrai projet.

Ce message signifie que le Docker Engine, présenté au guide 4, ne tourne pas. C'est l'erreur la plus fréquente chez les débutants. Vérifiez que Docker Desktop est bien ouvert et que son icône indique qu'il est prêt, comme vu au guide 5. Si Docker Desktop vient d'être lancé, patientez quelques secondes avant de retenter la commande : le démarrage complet du moteur n'est pas toujours instantané.
Cela signifie que le terminal ne connaît pas encore la commande docker, généralement parce qu'il a été ouvert avant la fin de l'installation de Docker Desktop. Fermez complètement le terminal, rouvrez-en un nouveau, et réessayez. Si le problème persiste, vérifiez que l'installation de Docker Desktop s'est bien terminée jusqu'au bout, comme décrit au guide 5.
Ce message (souvent « port is already allocated » ou « address already in use ») signifie que le port de l'hôte demandé, celui qui précède les deux-points dans l'option -p, est déjà occupé par un autre conteneur ou par un programme de votre ordinateur. Vérifiez avec docker ps si un autre conteneur utilise déjà ce port, arrêtez-le si besoin, ou choisissez simplement un autre port de l'hôte disponible, comme pratiqué au guide 16.
Un conteneur reste actif tant que le processus lancé par son instruction CMD tourne, comme expliqué au guide 13. S'il s'arrête immédiatement, ce processus s'est terminé, souvent à cause d'une erreur. Le réflexe à avoir systématiquement : consulter docker logs sur ce conteneur, même arrêté, avec docker logs suivi de son nom. Le message d'erreur affiché révèle presque toujours la cause exacte, par exemple une dépendance manquante ou une erreur dans le code de l'application.
Cette erreur signifie que Docker n'a pas trouvé l'image demandée sous le nom exact indiqué, souvent à cause d'une faute de frappe dans le nom ou le tag. Vérifiez l'orthographe exacte de l'image, en particulier si elle ressemble à une image officielle : nginx s'écrit nginx, pas Nginx ni nginx-official. Si l'image est censée avoir été construite localement avec docker build, vérifiez aussi que la construction s'est bien terminée sans erreur avant de tenter de la lancer.
Ce message indique que l'utilisateur qui exécute une commande, à l'intérieur du conteneur ou lors de la construction de l'image, n'a pas les droits nécessaires pour accéder à un fichier ou un dossier. C'est une cause fréquente si une instruction USER a été placée trop tôt dans un Dockerfile, comme évoqué au guide 29, avant que les fichiers concernés n'aient les bons droits. Sous Linux et macOS, cela peut aussi venir des permissions du dossier partagé lui-même, en cas de bind mount.
Vérifiez d'abord le chemin exact utilisé après les deux-points dans l'option -v ou volumes : il doit correspondre précisément à l'endroit où l'application écrit réellement ses fichiers à l'intérieur du conteneur, comme /app/data pour Mini-Carnet au guide 18. Une faute de frappe dans ce chemin, ou un chemin différent de celui réellement utilisé par le code, donne l'impression qu'un volume ne fonctionne pas alors qu'il est simplement relié au mauvais endroit.
Sous Windows, un chemin de fichier utilise des antislashs (comme C:\Users\Nom\projet), alors que Docker attend une syntaxe de type Unix, avec des slashs. La plupart des terminaux modernes sous Windows convertissent automatiquement ce format pour Docker Desktop, mais un chemin copié tel quel depuis l'explorateur de fichiers peut poser problème. En cas de doute, ouvrez un terminal directement dans le dossier concerné, et utilisez un chemin relatif ou le point . plutôt qu'un chemin absolu recopié à la main.
Vérifiez d'abord que le nom de la variable, dans -e ou environment, correspond exactement, y compris la casse, à ce que le code lit avec process.env dans le cas de Node.js. Une variable APP_NAME ne sera jamais lue si le code cherche App_Name ou app_name : ces trois écritures sont considérées comme différentes. Vérifiez ensuite, avec docker exec et la commande env comme vu au guide 19, que la variable est réellement présente à l'intérieur du conteneur en cours d'exécution.
Comme expliqué au guide 20, deux conteneurs ne peuvent se joindre par leur nom que s'ils partagent le même réseau personnalisé, ou le même fichier Compose. Vérifiez avec docker network ls et docker network inspect que les deux conteneurs concernés sont réellement sur le même réseau. Avec Docker Compose, ce cas est rare puisque tous les services d'un même fichier rejoignent automatiquement le même réseau, comme vu au guide 25 ; il apparaît surtout en mélangeant des conteneurs lancés séparément avec docker run.
Le journal affiché par docker build indique, ligne par ligne, quelle instruction du Dockerfile est en cours d'exécution au moment de l'échec. Repérez la dernière étape affichée avant le message d'erreur : c'est presque toujours elle la cause directe. Une erreur pendant une instruction RUN npm install signale généralement un problème de dépendances (nom mal orthographié dans package.json, ou dépendance qui n'existe plus) ; une erreur pendant COPY signale le plus souvent un fichier absent ou un chemin incorrect.
La méthode qui fonctionne presque toujours

Face à une erreur inconnue de cette liste : lisez le message en entier, sans le survoler, il contient presque toujours l'information clé. Consultez ensuite docker logs sur le conteneur concerné. Enfin, recherchez le message d'erreur exact, entre guillemets, dans la documentation officielle Docker plutôt que sur un forum au hasard : c'est la source la plus fiable et la plus à jour.

Vérifiez que vous avez compris

Un conteneur s'arrête immédiatement après son lancement, sans message d'erreur visible dans votre terminal. Quelle est la toute première commande à taper pour comprendre pourquoi ?

docker logs, suivi du nom ou de l'identifiant du conteneur. Même arrêté, un conteneur conserve ce qu'il a affiché avant de s'arrêter, et cette sortie contient presque toujours l'indication précise de ce qui a mal tourné, comme rappelé plusieurs fois dans ce guide.

Chapitre terminé