A debugging workflow

When a container will not start, keeps restarting, or behaves oddly, guessing wastes time. There is a repeatable order to work through, and it resolves most problems quickly. This node lays out the workflow; the next ones cover each tool in detail.

The order to check things

1. Is it running, and what is its status? Start with docker ps -a. Is the container up, exited, or restarting? Note the exit code in the status - it is your first clue.
2. What did it print? Read docker logs. Most failures announce themselves here: a missing environment variable, a config error, a failed connection. This solves the majority of cases on its own.
3. How is it configured? If the logs are not enough, use docker inspect to check the environment variables, mounts, networks, and command it actually got - often different from what you intended.
4. What does it look like from inside? For a running container, docker exec a shell and look around - check files, test a network call, run the command by hand.
5. Is it a resource problem? If it is being killed or is slow, docker stats shows live memory and CPU use. A container hitting a memory limit gets killed with exit code 137.

Work from cheap to expensive

The order is deliberate: each step costs a little more effort than the last, and the cheap early steps solve most problems. Checking status and logs takes seconds and answers the common cases. Only escalate to inspecting, shelling in, and watching resources when the simple checks come up empty.

Do not restart blindly

The tempting move when a container misbehaves is to restart it and hope. Sometimes that clears a transient glitch, but it also destroys the state that would tell you what went wrong, so the problem often returns with no new information. Diagnose first - read the status and logs - then restart deliberately if the evidence points that way.