Docker · Lesson 10 of 11 · 4 min read
Troubleshooting Docker
Common failures and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| Container exits immediately, code 0 | Command finished; process daemonised into background | Run the app in the foreground (nginx -g 'daemon off;') |
| Exits with code 1 | App error | docker logs; run interactively with --entrypoint sh to explore |
| Exit 127 | Command not found (wrong path, missing in slim image, Windows line endings in script \r) |
Check ENTRYPOINT path, install the tool, dos2unix |
| Exit 126 | Not executable | chmod +x in the Dockerfile (COPY --chmod=755 in BuildKit) |
| Exit 137 | SIGKILL — OOM killed (OOMKilled: true) or killed after stop timeout |
Raise memory or fix leak; handle SIGTERM |
| Exit 139 | Segfault (SIGSEGV) | Often architecture or libc mismatch (glibc binary on Alpine/musl, amd64 image on arm64) |
exec format error |
Image architecture doesn't match the host | Build multi-arch with buildx |
no space left on device |
/var/lib/docker full |
docker system df, prune, cap logs |
port is already allocated |
Another container/process has the host port | ss -tlnp, change host port |
toomanyrequests pulling from Docker Hub |
Rate limit | Authenticate, mirror, ECR pull-through cache |
| Build very slow | Big context, cache invalidated early | .dockerignore, reorder layers, BuildKit cache |
| App works locally, fails in container | Binds to 127.0.0.1; missing env vars; file permissions; timezone/locale | Bind 0.0.0.0; compare docker inspect env; check UIDs |
| Permission denied writing a mounted volume | UID mismatch between container user and host dir | chown to container UID, or use named volumes; fsGroup in K8s |
| Same image behaves differently in prod | Different env, config, secrets, mounts, limits, architecture | Diff docker inspect/pod spec; check uname -m |
| Can't reach another container by name | Using default bridge | Use a user-defined network |
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.
A debugging sequence
docker ps -a— state and exit code.docker logs <c>— app output.docker inspect <c>—State(OOMKilled, ExitCode, Error),Config(cmd, env),Mounts,NetworkSettings.docker run --rm -it --entrypoint sh <image>— explore the image.docker exec -it <c> shor attach a netshoot container to its namespaces.docker eventsand the daemon logs (journalctl -u docker).
Enlarge diagram
Swipe sideways to see all of it, or tap to open it full screen.