docker/podman run exit codes: 125, 126, 127, and the signal codes that reach through them

What it is

Docker's own documentation for docker run reserves three low codes for failures that never reached the containerized process at all, and passes everything else straight through:

Code	Meaning	Typical cause
125	"the error is with Docker daemon itself"	Bad docker run flags, daemon-side failure, image pull failure
126	"the specified contained command can't be invoked"	Entrypoint exists but is not executable, or is a directory
127	"the contained command can't be found"	Typo'd binary name, missing from the image, wrong $PATH in the image
137	passed through from the container = 128+9	Container process received SIGKILL — very often the kernel OOM killer
139	passed through = 128+11	Container process received SIGSEGV (crash)
143	passed through = 128+15	Container process exited on SIGTERM (e.g. docker stop); a PID 1 without a TERM handler ignores it, so docker stop escalates to SIGKILL and you see 137
anything else	"represent[s] the exit code of the provided container command"	The containerized process's own exit code

Why it matters

125/126/127 tell you the failure happened before your program ran — a Dockerfile/entrypoint/image problem, not a bug in your application. 137 is the opposite trap: it is easy to assume "container crashed," but 137 is just 128+SIGKILL, and SIGKILL against a container is the standard way both docker kill and the Linux out-of-memory killer terminate a process — the number alone does not distinguish an operator-issued kill from an OOM event.

How to apply

• Branch on 125/126/127 first: fix the image/entrypoint/command rather than retrying the workload.
• For 137, don't stop at the exit code — the Moby project's own API specification documents a dedicated OOMKilled boolean on the container's state, described as recording "whether a process within this container has been killed because it ran out of memory since the container was last started." Check it with docker inspect --format '{{.State.OOMKilled}}' <container>, but treat false as inconclusive: on some cgroup-v2 hosts it stays false although the kernel log (journalctl -k) records a "Memory cgroup out of memory" kill.
• For 139, treat it as an application bug (segfault) inside the container, not an infrastructure issue.
• For 143, correlate with whether your own orchestration issued a stop/restart; it is expected during rolling deploys.

Pitfalls

• Assuming every 137 is an OOM kill; a manual docker kill, or docker stop after its grace period, produces the same 137.
• An entrypoint built for another CPU architecture, or a script without a #! line, fails with exec format error and exit 255 on current runc — not 126.
• Treating 125 the same as the container command's own failure — 125 means the daemon rejected the run, so the container's application logs will be empty or nonexistent.