0 / 11 lessons — 0%
Lesson 10 / 11 🔍
Debugging & troubleshooting
Every Docker user hits the same handful of failures. Here's the field guide, so the first time isn't spent panicking.
| Symptom | Usual cause | First move |
|---|---|---|
| Container exits immediately | Main process finished or crashed instantly | docker logs <name> — the exit reason is almost always right there |
port is already allocated | Something else already owns that host port | docker ps to find the conflicting container, or pick a different host port |
permission denied inside container | Files owned by a different UID than the container's user | Check the Dockerfile's USER, or the ownership of the mounted volume |
no space left on device | Old images/containers/volumes piling up | docker system prune (careful — it deletes stopped stuff) |
| Container is "unhealthy" | Its HEALTHCHECK command is failing | docker inspect --format='{{json .State.Health}}' <name> |
# the debugging toolkit, roughly in the order you'd reach for them docker logs -f --tail 100 myapp # what did it say before it died? docker inspect myapp # full JSON: env vars, mounts, network, exit code docker exec -it myapp sh # climb inside a running container docker stats # is it a resource problem? docker events # live stream of what Docker is doing right now
"It exited with code 0 immediately" is not a bug report — it means the container's main process finished successfully and had nothing left to do. If that's a web server, it should never exit on its own; check that your
CMD actually starts a long-running process in the foreground.Try it yourselfDeliberately break something: run
docker run -p 8080:80 nginx twice in a row without stopping the first. Read the exact error Docker gives you — you'll recognize it instantly next time it happens for real.