Docker Error Troubleshooting — The Complete Guide

Docker Error Troubleshooting — The Complete Guide#

Docker is simple until it isn't. The moment something breaks, you get a terse one-line error and a container that either won't start, exits instantly, or refuses to talk to anything. The good news is that almost every Docker problem is one of a small, well-known set. This guide is the map: for each common error it explains what actually went wrong, the command that reveals the cause, and where the fix lives.

The universal first move, before any specific error, is to ask Docker what happened:

docker ps -a                 # is it running, or Exited with a code?
docker logs <container>      # what did it print before dying?
docker inspect <container>   # config, mounts, exit code, OOMKilled flag
docker events                # live stream of what the daemon is doing

Nine times out of ten the exit code and the last few log lines tell you everything.

"I can't even talk to Docker"#

Two errors stop you before you start:

• Permission denied on the socket: "Got permission denied while trying to connect to the Docker daemon socket." Your user isn't in the docker group. Fixed in Docker permission denied.
• Cannot connect to the daemon: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running?" The daemon is stopped or you're pointed at the wrong host. Fixed in cannot connect to the Docker daemon.

"The container won't stay up"#

• Container exits immediately: it starts, then docker ps -a shows Exited. Usually the main process finished or forked into the background, so PID 1 exited. Walked through in container exits immediately.
• Exit code 137 (OOM): the container was killed for exceeding its memory limit. Covered in Docker exit code 137. (The Kubernetes equivalent is OOMKilled.)
• exec format error: you're running an image built for a different CPU architecture (arm64 image on amd64 or vice versa). Fixed in Docker exec format error.

"It won't build or bind"#

• Port is already allocated: another process or container already holds the host port. Fixed in port already allocated.
• No space left on device: Docker filled the disk with images, layers, volumes, and build cache. Reclaimed in no space left on device.
• Slow or broken build cache: rebuilds that redo everything, or a cache that serves stale layers. Fixed in Docker build cache, and a tight .dockerignore prevents half of it.
• Compose failures: env vars not interpolating, depends_on not waiting for readiness, network name clashes. Covered in docker-compose errors.

The mental model#

Docker problems cluster into four buckets: you can't reach the daemon (socket/permissions), the container won't stay up (PID 1 / OOM / arch), it won't build or bind (cache / disk / ports), or Compose is wiring things wrong. Naming the bucket from docker ps -a plus the exit code turns a cryptic message into a short checklist. Once the basics are solid, harden the image (multi-stage builds, image hardening) so there's less to go wrong.

The call we'd make#

Read the exit code and the last log lines first; they answer most of these in seconds. Learn the four buckets so a new error slots into one before you start guessing. Each linked guide is the fast path for a specific failure. Docker rewards a small amount of memorization: the same dozen errors will follow you across every project, and turning each into a reflex is what separates a five-minute fix from a lost afternoon.