Debugging a Docker Container That Won’t Start

A container that starts and immediately dies is one of Docker's most common frustrations — especially because docker ps shows nothing, since the container already exited. The trick is knowing where Docker keeps the evidence.

1. See it even though it exited

docker ps -a (note the -a) shows stopped containers and their exit code in the STATUS column. Exited (0) means it ran to completion (maybe it has no long-running process); any non-zero code means it failed — and 137 again means it was OOM-killed.

2. Read the logs

docker logs <container>            # stdout/stderr from the failed run
docker logs --tail 50 <container>
docker compose logs web            # the compose equivalent

The application's own error almost always prints here — a missing env var, a port bind failure, a config file it couldn't find.

3. Inspect config and the common traps

• Bad command/entrypoint — the container has nothing to keep running. Confirm the CMD.
• Port already in use — bind: address already in use means something else owns the host port.
• Missing env/volume — docker inspect <container> shows the resolved env, mounts, and restart policy.
• Image not what you think — a stale tag; re-pull or rebuild.

4. Debug interactively

When the logs aren't enough, override the entrypoint and poke around inside: docker run --rm -it --entrypoint sh <image>. Now you can check whether the files, config, and binaries the app expects are actually in the image.

Practise container incidents

Crashed containers and failed deployments are incidents in the simulator (diagnostic docker commands are free — they don't count as failed fix attempts). Work them in a full incident response shift, and if it's a proxy returning 502 see fixing 502 Bad Gateway.