Docker Error Troubleshooting: The Complete Guide

Start with docker ps -a for the exit code and docker logs <container> for the last lines; those two commands identify most Docker failures in seconds. Then match the error to one of four buckets: can't reach the daemon, container won't stay up, won't build or bind, or Compose wiring.

The universal first move, before any specific error:

$ docker ps -a                 # running, or Exited with a code?
$ docker logs --tail 50 <container>   # what it printed before dying
$ docker inspect --format '{{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}' <container>
$ docker events                # live stream of what the daemon is doing

The exit code and the last few log lines tell you almost everything. Below is each bucket, the exact error strings you'll see, the one command that confirms the cause, and the fix.

Bucket 1: "I can't even talk to Docker"

Two errors stop you before you start, and they look alike but mean different things.

Got permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock. The daemon is running; your user can't open the socket. Confirm with ls -l /var/run/docker.sock (owner root, group docker, mode srw-rw----) and id (no docker group). Fix: sudo usermod -aG docker $USER, then newgrp docker or log back in. The security catch is in Docker permission denied.

Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? Either nothing is listening or you're pointed somewhere else. Docker's own troubleshooting page names exactly those two causes. Check both:

$ sudo systemctl is-active docker        # "inactive" or "failed" = daemon is down
$ env | grep DOCKER_HOST                 # set to a dead host or socket?
$ docker context ls                      # which endpoint the CLI is using
$ sudo journalctl -xu docker.service -n 50   # why the daemon refused to start

If the daemon is down, sudo systemctl start docker. If DOCKER_HOST points at a stale socket, unset DOCKER_HOST and remove it from ~/.bashrc. On WSL2 with Docker Desktop, the daemon lives in Desktop, so start the app and enable WSL integration for your distro. Full walkthrough: cannot connect to the Docker daemon.

Bucket 2: "The container won't stay up"

Docker's run reference reserves three exit codes for itself: 125 means the daemon or docker run failed, 126 means the command couldn't be invoked, 127 means it couldn't be found. Every other code is your process's own.

• Container exits immediately, Exited (0): PID 1 finished or forked into the background. A container lives exactly as long as its main process. nginx needs daemon off;, Apache needs -D FOREGROUND. Walked through in container exits immediately.
• Exited (127) with exec: "app": executable file not found in $PATH: typo in CMD, or the binary isn't in the image. Run docker run -it --entrypoint sh <image> and look.
• Exited (137): 128 + 9, a SIGKILL. If docker inspect shows OOMKilled=true, the container hit its memory limit; raise --memory or fix the leak. Covered in Docker exit code 137, with the Kubernetes version in OOMKilled.
• exec /usr/local/bin/app: exec format error: the image was built for another CPU architecture, typically an arm64 image on an amd64 host or the reverse. Check with docker image inspect --format '{{.Architecture}}' <image> against uname -m. Fixed in Docker exec format error.

Bucket 3: "It won't build or bind"

Bind for 0.0.0.0:8080 failed: port is already allocated. Another container or a host process holds the port. Find it with docker ps --filter publish=8080 and, for host processes, sudo ss -ltnp 'sport = :8080'. Stop it or publish on another port (-p 8081:8080). Details in port already allocated.

no space left on device. Images, stopped containers, volumes, and build cache filled the disk. See where it went before deleting anything:

$ docker system df            # TYPE, TOTAL, ACTIVE, SIZE, RECLAIMABLE per category
$ docker builder prune        # build cache, usually the biggest win
$ docker image prune -a       # images not used by any container

Leave docker system prune --volumes for when you know no volume holds data you need. Reclaimed in no space left on device.

Builds that redo everything, or serve stale layers. Usually an early COPY . . that invalidates every later layer, or a missing .dockerignore that sends node_modules and .git as build context. Fixed in Docker build cache; a tight .dockerignore prevents half of it.

DNS failures inside builds or containers (Temporary failure in name resolution). Common on hosts whose resolver is 127.0.0.1 (dnsmasq, systemd-resolved stubs), which a container's network namespace can't reach. Set explicit servers in /etc/docker/daemon.json with a "dns" array, then restart the daemon.

Bucket 4: Compose wiring

Compose errors are rarely Docker errors. The common three: variables that don't interpolate because the .env file isn't next to the compose file, depends_on that only waits for a container to start, not to be ready (use condition: service_healthy with a healthcheck), and network or container name clashes between projects. Covered in docker-compose errors.

The mental model

Name the bucket from docker ps -a plus the exit code, and a cryptic message becomes a short checklist. Once the basics are solid, harden the image (multi-stage builds, image hardening) so there's less to go wrong.

Questions people ask

How do I troubleshoot a Docker container that keeps failing?

Run docker ps -a to get the exit code, then docker logs --tail 50 <container> for the last output. Code 0 means the main process finished, 127 means a missing command, 137 means it was killed (check OOMKilled). If the logs are empty, start a shell in the image with docker run -it --entrypoint sh <image> and run the command by hand.

What does "Cannot connect to the Docker daemon" mean?

The CLI found no daemon at the address it tried. Either dockerd isn't running (sudo systemctl is-active docker, then sudo systemctl start docker) or DOCKER_HOST or the active context points at a socket that no longer exists. It is different from "permission denied", where the daemon is running but your user isn't allowed to open the socket.

How do I fix "docker daemon not running" on WSL?

With Docker Desktop, the daemon runs inside Desktop, so start the app and enable WSL integration for your distro in its settings. With Docker Engine installed directly in the distro, start it yourself: sudo systemctl start docker if systemd is enabled in WSL, otherwise sudo service docker start. Then confirm with docker info.

The call we'd make

Read the exit code and the last log lines before anything else; as of 2026 that still answers most Docker failures in under a minute. Learn the four buckets so a new error slots into one before you start guessing, and use each linked guide as the fast path for its failure. The same dozen errors follow you across every project, and turning each into a reflex is what separates a five-minute fix from a lost afternoon.

Sources

• Docker Docs: Troubleshoot the Docker daemon
• Docker Docs: Running containers, exit status
• Docker Docs: docker system df
• Docker Docs: Linux post-installation steps