Intermediate By Samson Tanimawo, PhD Published Sep 20, 2026 5 min read

Docker Debug Cheat Sheet

When the container won't start, won't stop, or won't behave, these commands tell you why. Skip the docs; type these.

List and filter

Start by knowing what's running, what crashed, and what's about to.

docker ps, running containers
docker ps -a, including stopped and exited
docker ps -a --filter status=exited, only exited containers
docker ps --filter health=unhealthy, failing healthchecks
docker ps --filter "label=app=api", by label
docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}", clean table for your eyes
docker ps -q, IDs only; pipe into other commands
docker ps --latest, last container created

The first stop. --since is the flag that turns 10,000-line logs into the 200 lines you actually need.

docker logs <container>, full logs
docker logs -f <container>, follow
docker logs --tail 200 <container>, last 200 lines
docker logs --since 10m <container>, last 10 minutes
docker logs --until 2026-04-16T14:00:00 <container>, up to a timestamp
docker logs --timestamps <container>, prepend wallclock to each line
docker logs <container> 2>&1 | grep -i error, both streams together (logs writes to stderr by default)

Get a shell inside. Try bash first, fall back to sh, fall back further to nsenter.

docker exec -it <container> bash, interactive shell
docker exec -it <container> sh, for slim/alpine images
docker exec <container> env, environment without interactive shell
docker exec <container> cat /etc/hosts, quick file peek
docker exec --user root -it <container> sh, root shell when the default user is locked down
docker cp <container>:/app/file.log ./file.log, copy file out
docker cp ./script.sh <container>:/tmp/, copy file in

Everything Docker knows about a container or image, in one JSON blob. Pair with jq.

docker inspect <container>, full JSON
docker inspect --format '{{.State.Status}}' <container>, running, exited, restarting
docker inspect --format '{{.State.ExitCode}}' <container>, exit code (137 = OOMKilled, 143 = SIGTERM)
docker inspect --format '{{.State.OOMKilled}}' <container>, boolean for OOMKill
docker inspect --format '{{.NetworkSettings.IPAddress}}' <container>, internal IP
docker inspect --format '{{json .Mounts}}' <container> | jq, volumes and bind mounts
docker inspect <image>, works on images too; check .Config.Cmd and .Config.Entrypoint

Live CPU, memory, network IO, block IO per container. Use it to confirm a container is hot before you start blaming it.

docker stats, live for all running containers
docker stats --no-stream, single snapshot, scriptable
docker stats <container>, single container
docker stats --format "table {{.Name}}\t{{.CPUPerc}}\t{{.MemUsage}}", clean output
docker top <container>, processes inside the container, host PIDs visible
docker events --since 1h, container lifecycle events (start, die, OOMKill)
docker events --filter event=oom, OOMKills only

Docker fills disks. Reclaim space carefully.

"My container can't reach the database." Half the time it's networks, half the time it's DNS, occasionally it's actually the database.

docker network ls, list networks
docker network inspect bridge, what's connected, gateway, subnet
docker port <container>, published port mappings
docker exec <container> cat /etc/resolv.conf, DNS the container sees
docker exec <container> getent hosts db, name resolution test
docker run --rm --network=<net> nicolaka/netshoot, temporary debug container with curl, dig, nslookup, tcpdump, mtr