Ordered checklists for CrashLoopBackOff, ImagePullBackOff, Pending, OOMKilled and other pod states, each step saying what the output tells you.
CrashLoopBackOff
5 common causes · 5 steps in order
The container started, exited, and has been restarted — repeatedly. The 'BackOff' is the important half: the kubelet is now waiting before each retry, doubling the delay up to five minutes. So a pod in this state is not continuously crashing; it is mostly sitting idle between attempts.
kubectl logs <pod> --previousThe current instance may not have started yet, so plain `kubectl logs` often returns nothing or a partial line. `--previous` reads the instance that died. If it shows a stack trace or a configuration error, that is the answer. Note the kubelet keeps only one previous instance.
kubectl describe pod <pod>Look at Last State under the container. Exit code 1 is an application error; 137 is SIGKILL, which with Reason: OOMKilled means the memory limit; 139 is a segfault; 143 is SIGTERM, meaning something asked it to stop. Exit code 0 with a restart means the process completed — the image is not running a server.
kubectl describe pod <pod>An event reading 'Liveness probe failed' before each restart means the probe is killing a container that was starting normally. The fix is a `startupProbe`, or a longer `initialDelaySeconds` — not a longer liveness period, which delays detection of real failures too.
kubectl events --for pod/<pod>Events are retained for about an hour. They carry scheduling and image-pull context that the pod's own status no longer shows once it has moved on.
kubectl debug <pod> -it --image=busybox:1.36 --target=<container>An ephemeral debug container joins the pod's namespaces, so it can see the same filesystem mounts, environment and network as the failing container without needing a shell in the image itself. If the mounted config file is empty or absent, that is usually the cause.
Deleting the pod. A Deployment recreates it immediately into the same state, the previous logs are lost along with the old pod, and the only thing that changes is that the back-off timer resets.
This is reference material and not a diagnostic: nothing here has looked at your cluster, so it cannot know which state your pod is in or why. The checklists are ordered by what tends to be the answer, which is not the same as what is the answer this time. One thing worth knowing before you start: Kubernetes keeps events for about an hour by default, so a problem from yesterday has left no event behind, and the kubelet retains only one previous container instance — a pod that has restarted twice has already discarded the logs from the first failure.
Kubernetes Pod Troubleshooting runs entirely on your device — this is maintained reference text, and no cluster is contacted.
You’re on the Free plan. Compare plans
What makes a checklist useful is the reading, not the command. Plenty of pages list `kubectl describe pod` as step one for every problem — true, and nearly useless. What is missing is what the output means.
That exit code 137 with reason OOMKilled is the container's own memory limit, while a pod with status Evicted is the node running short, and the two need completely different fixes. That a FailedScheduling event's per-node counts add up to the cluster size and therefore say exactly which constraint is binding. That `manifest unknown` and `unauthorized` are both ImagePullBackOff and have nothing in common. Every step here says what each likely answer tells you.
Each state also names its antipattern — the thing people reach for that does not help. Deleting a CrashLoopBackOff pod recreates it into the same state and destroys the previous logs, which were the only evidence. Removing a memory limit turns a contained failure into a node-wide one. Those are worth saying out loud, because they are what gets tried first.
Two things are worth knowing before you start. Kubernetes keeps events for about an hour by default, so a problem from yesterday has left no event behind. And the kubelet retains only one previous container instance, so a pod that has restarted twice has already discarded the logs from its first failure.
This is reference material, not a diagnostic. Nothing here has looked at your cluster, so it cannot know which state your pod is in or why.
Because of the back-off half of the name. The kubelet waits before each retry and doubles the delay up to five minutes, so a pod in this state is mostly idle between attempts rather than crashing continuously. That also means `kubectl logs` without `--previous` often returns nothing.
OOMKilled is the container exceeding its own memory limit — the kernel killed the process, exit code 137. Evicted is the kubelet removing the whole pod to reclaim memory or disk on the node, and it picks victims by QoS class. Different causes, different fixes, and the first step in the checklist is telling them apart.
The readiness probe. A failing readiness probe excludes the pod from the Service's endpoints and does not restart anything, so the pod looks healthy while receiving no traffic. That state has its own checklist here, including the case where the app is bound to 127.0.0.1 and the kubelet is probing the pod IP.
No. It is maintained reference text and contacts nothing, so it cannot tell you which state your pod is in. The checklists are ordered by what tends to be the answer, which is not the same as what is the answer this time.