# Docker Error Troubleshooting: The Complete Guide URL: https://www.devopsness.com/blog/docker-error-troubleshooting-guide Author: Kiril Urbonas Published: 2026-07-16 Updated: 2026-10-03 Categories: DevOps Tags: Docker, Containers, DevOps, Debugging, Operations Summary: Most Docker time is spent fighting the same handful of errors. This is the map: what each one means, the command that reveals the cause, and the fix. --- # Docker Error Troubleshooting: The Complete Guide Start with `docker ps -a` for the exit code and `docker logs ` 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: ```bash $ docker ps -a # running, or Exited with a code? $ docker logs --tail 50 # what it printed before dying $ docker inspect --format '{{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}' $ 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](/blog/fix-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: ```bash $ 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](/blog/fix-cannot-connect-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](/blog/fix-docker-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 ` 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](/blog/fix-docker-oom-137), with the Kubernetes version in [OOMKilled](/blog/fix-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}}' ` against `uname -m`. Fixed in [Docker exec format error](/blog/fix-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](/blog/fix-docker-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: ```bash $ 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](/blog/fix-docker-no-space-left). **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](/blog/fix-docker-build-cache); a tight [.dockerignore](/blog/dockerignore-best-practices) 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](/blog/fix-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](/blog/docker-multi-stage-builds-optimizing-image-size), [image hardening](/blog/best-practices-docker-image-hardening-for-production)) 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 ` 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 ` 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](https://docs.docker.com/engine/daemon/troubleshoot/) - [Docker Docs: Running containers, exit status](https://docs.docker.com/engine/containers/run/) - [Docker Docs: docker system df](https://docs.docker.com/reference/cli/docker/system/df/) - [Docker Docs: Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/)