How to read Kubernetes exit codes to see why a container died

Three Pods keep restarting, and the RESTARTS column keeps climbing. That number only tells you something died, not why. The exit code is the first clue. Each of these containers left one behind, and decoding it tells you where to look next.

In kubectl describe, State is the container running right now. Last State is the one that died. Read Reason and Exit Code together: here, OOMKilled and 137. The same fields live in the Pod status, under containerStatuses, lastState, terminated, if you'd rather script it.

An exit code splits into two ranges. From 1 to 127, the app picked the number itself when it quit. Above 128, a signal ended the process, so subtract 128 to get the signal number. That one subtraction tells you who or what stopped the container.

Take api-7d9f. It starts, tries to load its config, and that step fails. The app throws an error and exits with code 1 on its own. No signal killed it. The app made that choice, so the explanation is in its own output.

Exit code 1 means the app chose to fail, so ask it why. The --previous flag matters, because it shows logs from the crashed run, not the fresh restart. Here, the output says DATABASE_URL is missing, and that's the reason it exited with 1. This output is illustrative.

Now the worker. Its memory climbs past the limit, and the kernel steps in with SIGKILL, signal nine. The process gets no chance to clean up. Kubelet records the death as 137, because 128 plus 9 is 137, and the reason says OOMKilled. That confirms memory. Then kubelet restarts the container.

Exit code 137 only tells you SIGKILL was sent. It doesn't say why. On the left, memory crosses the limit and the container is killed instantly. On the right, it ignored a stop request, the grace period ran out, and it was force-killed. Always read Reason beside the code.

A container shows exit code 137, but Reason says Error instead of OOMKilled. What is the most likely cause?

It was force-killed after the grace period. 137 means SIGKILL, signal nine, so something outside the app killed it. Without OOMKilled in the Reason field, memory is not the confirmed cause; a common alternative is a forced kill after the termination grace period ran out.

Now web-8f4a. Exit code 143 is 128 plus 15, and 15 is SIGTERM, a polite request to stop. In the sequence, the liveness probe fails, the Kubelet sends SIGTERM, web shuts down with 143, and then it restarts. So when you see 143 with restarts, check Events in describe for probe failures.

An exit code narrows the search, but it never proves the root cause. Apps can return any code they like. So confirm it with Reason and Events, then read the logs with kubectl logs --previous.

Above 128, a signal killed it, so subtract 128 to name the signal. Api's 1 was the app's own error. Worker's 137 is signal 9, and web's 143 is signal 15. Then check Reason to confirm.