Why Your Docker Container Stops: Decoding Common Exit Codes

Why is my container not running?

Understanding Docker container exit codes is essential for diagnosing why a container stops; the exit code indicates the reason for termination. This guide lists the most common codes and the actions that trigger them.

Exit codes are process return values generated via the exit_group system call. In POSIX, 0 means normal exit, while 1‑255 indicate errors, with most generic errors using code 1.

How to view exit codes

Method 1: Inspect the pod in Kubernetes $ kubectl describe pod xxx Method 2: Use Docker commands

$ docker ps --filter "status=exited"
$ docker inspect <container-id> --format '{{.State.ExitCode}}'

Method 3: Manually output the exit code

$ docker container run alpine sh -c "exit 1"
$ docker container ls -a
CONTAINER ID   IMAGE   COMMAND               CREATED          STATUS
61c688005b3a   alpine  "sh -c 'exit 1'"   About a minute ago   Exited (1) 3 seconds ago

Common exit codes

Exit Code 0

The container has no foreground process attached.

It is an exception to all other exit codes.

It does not necessarily indicate a problem; it can be used to stop a container automatically after its work is done.

Exit Code 1

Program error or missing file referenced in the Dockerfile (e.g., wrong entrypoint).

Errors can be simple (division by zero) or complex (null reference, crash).

Exit Code 137

Container received SIGKILL (kill -9).

Triggered by docker kill or the Docker daemon.

Often occurs when pod resource limits are too low, causing OOMKilled.

Exit Code 139

Container received SIGSEGV (kill -11), indicating an invalid memory reference.

Usually caused by buggy code or a faulty base image.

Exit Code 143

Container received SIGTERM (kill -15), typically from docker stop.

Sometimes docker stop leads to Exit Code 137 if the process does not handle SIGTERM and Docker escalates to SIGKILL.

Less common exit codes

126: Permission problem or non‑executable command.

127: Command not found, often due to a typo in a shell script.

1 or 255: Custom exit codes; many programs use exit(1) or exit(-1) (which maps to 255).

Exit code ranges

Valid range is 0‑255; 0 means normal exit.

External interruptions produce codes 129‑255.

Program‑internal errors usually yield codes 1‑128.

If a negative code is specified, it is converted using 256 – (|code| % 256).

References

http://tldp.org/LDP/abs/html/exitcodes.html

https://imroc.io/posts/kubernetes/analysis-exitcode/

https://medium.com/better-programming/understanding-docker-container-exit-codes-5ee79a1d58f6