Troubleshooting guide
Docker container won't start? Find the cause, step by step
An error from docker run, a container that exits, or one that can't reach anything.
What happens?
- The docker command itself fails"Cannot connect to the Docker daemon", "permission denied"
- The image can't be pulled"pull access denied", "repository does not exist"
- docker run or compose up stops with an error
- It starts, then stopsdocker ps -a shows "Exited (…)"
- It runs, but can't reach a database or another service
What does the docker command say?
Likely cause
The image name, tag or login is wrong
Docker says "denied" both for an image that doesn't exist and for one you may not see. Check the full name (registry, namespace, image, tag), then whether you're logged in to that registry.
Check it
docker manifest inspect registry.example.com/team/app:1.4.3Not this?Start over
Which error does it stop with?
Which exit code does it show?
docker ps -a --format "table {{.Names}}\t{{.Status}}"Likely cause
localhost inside a container is the container itself
The app connects to localhost or 127.0.0.1 and reaches its own container. Use the other container's service name, or host.docker.internal for something on the host.
Read the fix: Docker: "connection refused" to localhost from a container — how to reach the hostNot this?Start over
Likely cause
Docker isn't running, or the client looks in the wrong place
The docker command is only a client: the engine (dockerd, or Docker Desktop) must be running, and the client must talk to it on the right socket or context.
Check it
sudo systemctl status docker --no-pager
docker context lsNot this?Start over
Likely cause
Your user may not use Docker's socket
Docker runs, and your user isn't in the docker group (or the shell doesn't know it yet). Add the user and log in again; don't chmod the socket.
Check it
ls -l /var/run/docker.sock
id -nGNot this?Start over
Likely cause
Something else already uses that host port
Another container, another Compose project or a program on the host holds the port you publish. Find it, then stop it or publish on another port.
Check it
docker ps --format "table {{.Names}}\t{{.Ports}}" | grep 8080Not this?Start over
Likely cause
The image was built for another CPU
An arm64 image on an amd64 server, or the other way round (often an image built on an Apple silicon Mac). Build or pull it for the server's platform.
Check it
docker image inspect -f "{{.Architecture}}" myapp:latest
uname -mNot this?Start over
Likely cause
It was killed: out of memory, or a stop that took too long
137 is 128 + 9, SIGKILL. Docker records which: OOMKilled=true means it went over its memory limit; false means docker stop killed it after SIGTERM was ignored.
Check it
docker inspect -f "{{.State.ExitCode}} OOMKilled={{.State.OOMKilled}}" apiNot this?Start over
Likely cause
The main process finished
A container lives as long as its main process. A command that starts a service in the background and returns (or a script that ends) stops the container, without any error. Run the program in the foreground, for example nginx -g "daemon off;".
Check it
docker inspect -f "{{.Config.Cmd}} {{.Config.Entrypoint}}" apiNo article yet: the steps above are the fix.
Not this?Start over
What do the container's last logs say?
docker logs --tail 50 apiLikely cause
A program built for glibc, on Alpine
Alpine uses musl instead of glibc, so a binary built elsewhere can't find its loader, and the error names the program even though it exists.
Check it
docker run --rm --entrypoint sh myapp:latest -c "ldd /app/server"Not this?Start over
Likely cause
The application failed, not Docker
Docker started it; the program then stopped with its own error. Read the full log, and paste the error message into the search on this site: a missing environment variable or a bad configuration file are the usual causes.
Check it
docker logs api 2>&1 | tail -n 100No article yet: the steps above are the fix.
Not this?Start over
Have an exact error message? Paste it into search instead.
Every cause this guide covers
The same answers, all on one page, if you would rather scan them.
- The image name, tag or login is wrongDocker "pull access denied": the repository doesn't exist, or you're not logged in
- localhost inside a container is the container itselfDocker: "connection refused" to localhost from a container — how to reach the host
- Docker isn't running, or the client looks in the wrong place"Cannot connect to the Docker daemon. Is the docker daemon running?": every cause
- Your user may not use Docker's socketDocker: "permission denied while trying to connect to the Docker daemon socket"
- Something else already uses that host portDocker "port is already allocated" and "ports are not available": find who has the port
- The image was built for another CPUDocker "exec format error": the wrong CPU architecture, or a script with no shebang
- It was killed: out of memory, or a stop that took too longDocker "exited with code 137": OOM kill or a stop that took too long
- The main process finished
- A program built for glibc, on AlpineAlpine "not found" for a binary that's right there: glibc vs musl
- The application failed, not Docker