Exit Codes

## What an exit code is Every process on Linux ends with an 8-bit **exit status**, a number from 0 to 255 that it hands back to whoever started it. By universal convention `0` means success and anything non-zero means failure. In a shell you read it as `$?`. A container is a wrapper around one **main process** — PID 1 inside the container's namespace, the thing your `ENTRYPOINT`/`CMD` launched. The container's lifetime is that process's lifetime: when PID 1 exits, the container transitions to the `exited` state regardless of whether other processes are still alive inside it. The exit status of that process becomes the container's exit code, and the daemon stores it in the container's state record. ## Where to read it A stopped container still exists (with its filesystem, logs, and state) until you `docker rm` it, so the code survives the process. - `docker ps -a` lists stopped containers too; the STATUS column reads `Exited (1) 2 minutes ago`. This is the quickest look. - `docker inspect --format '{{.State.ExitCode}}' <container>` prints only the number, which is what you want in scripts. - The whole state block is worth knowing: `docker inspect --format '{{json .State}}' <container>` gives `Status`, `ExitCode`, `Error`, `OOMKilled`, `StartedAt`, `FinishedAt`. `Error` often carries the daemon's own message when the container never really started. - `docker wait <container>` blocks until the container stops and then prints its exit code — handy in CI scripts. - `docker run` in the foreground (without `-d`) passes the container's exit code through as the exit code of the `docker run` command itself, so `echo $?` after it works exactly as you'd expect. ## Reading 0 `0` means the main process ran to completion and reported success. For a batch job — a migration, a test run, a one-shot CLI — that is the outcome you wanted, and it is why CI pipelines gate on `docker run ... && next-step`. For a **long-running service**, exit 0 is not automatically good news. It means the server decided to stop on its own: it finished reading stdin and quit, it forked into the background and the foreground process returned (a classic mistake — the daemon "started" and PID 1 immediately exited), or it received a shutdown signal and its handler chose to `exit(0)`. A web server that shows `Exited (0)` seconds after launch is almost always a startup bug, not a clean run. ## Reading 1 `1` is the catch-all failure code. Language runtimes use it for an uncaught exception; shells use it for a failed command; most programs use it for "bad configuration, cannot continue". Concretely you'll see it when an environment variable is missing, a config file fails to parse, a required port is already bound, a database connection is refused at boot, or an entrypoint script hits `set -e` and a command failed. Because `1` is generic, it tells you *that* the application failed, never *why*. The next command is always `docker logs <container>` (add `--tail 50` on a noisy container). Applications that want to be more informative define their own codes — anything from 2 to 124 is fair game for an application to use for its own meanings, and some tools do (curl, for instance, has dozens). ## Why the code matters operationally The exit code is the input to everything downstream: - **Restart behaviour**: `--restart=on-failure` restarts only for non-zero exits, so a process that exits 0 by mistake will never be restarted. - **CI/CD**: a build step's pass/fail is literally the container's exit code. - **Orchestrators** surface the same number when they report a crash, so the vocabulary transfers. ## Ranges to be aware of Docker reserves some values so it can report failures that are the *daemon's* problem rather than the app's: `125` (the `docker run` invocation itself failed), `126` (the command was found but is not executable), `127` (the command was not found). And any container killed by a signal reports `128 + signal number` — `137` for SIGKILL (9), `143` for SIGTERM (15). So when a code looks strange, check whether it falls in one of those buckets before blaming application logic.