6.1.3.4 Container Exit Codes

Container exit codes are the numeric status a container's main process returns upon termination, recorded by Docker and inspectable afterward, providing a standardized way to determine whether a container's process completed successfully or encountered some specific failure.

Checking a Container's Exit Code

After a container stops, its exit code remains available for inspection, even though the container's process is no longer running.

docker run myapp:1.0
docker inspect myapp --format '{{.State.ExitCode}}'

Common Exit Code Conventions

An exit code of 0 conventionally indicates success; any non-zero value indicates some kind of failure, with specific non-zero values sometimes carrying additional, application-specific meaning.

docker run --rm myapp:1.0
echo $?

This immediately reports the exit code of the just-completed container's process, useful in scripts that need to react differently based on success or failure.

Distinguishing Different Kinds of Non-Zero Exit Codes

Certain exit code ranges carry conventional meaning in container contexts — 137, for instance, commonly indicates a process was killed by SIGKILL (128 + 9), which can be a useful clue when diagnosing why a container stopped unexpectedly.

docker inspect myapp --format '{{.State.ExitCode}}'

An exit code of 137 here suggests the container was forcibly killed, possibly due to exceeding a memory limit, rather than the application exiting on its own due to an internal error.

Using Exit Codes in Automation

CI pipelines and orchestration systems rely heavily on exit codes to determine whether a particular run succeeded, making consistent, meaningful exit code behavior in an application genuinely important for reliable automation.

docker run myapp:1.0 || echo "Container failed"

Why Container Exit Codes Matter

A container's exit code is often the most immediately available signal for determining what happened to a container after it stops, making consistent and meaningful exit code behavior an important quality for any containerized application to provide.