Opscraft
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 diagram01126127137139143finished normally (or daemonised into the background)application error: read the logsnot executable: chmod +xcommand not found: wrong path, missing tool, CRLF line endings128 + 9: SIGKILL, usually out of memory128 + 11: segfault, often wrong architecture or libc128 + 15: stopped with SIGTERM
Figure 1. Exit codes tell you how a container ended. Anything above 128 means it was killed by a signal (128 + signal number).
Swipe sideways to see all of it, or tap to open it full screen.

A debugging sequence

  1. docker ps -a — state and exit code.
  2. docker logs <c> — app output.
  3. docker inspect <c> — State (OOMKilled, ExitCode, Error), Config (cmd, env), Mounts, NetworkSettings.
  4. docker run --rm -it --entrypoint sh <image> — explore the image.
  5. docker exec -it <c> sh or attach a netshoot container to its namespaces.
  6. docker events and the daemon logs (journalctl -u docker).
Enlarge diagramdocker ps -astate and exit codedocker logswhat the app saiddocker inspectOOMKilled, env, mounts,networkrun with --entrypoint shexplore the imageexec or netshootlook inside while it runsevents + daemon logsjournalctl -u docker123456
Figure 2. A debugging sequence for a misbehaving container.
Swipe sideways to see all of it, or tap to open it full screen.