# Kubernetes Error Troubleshooting Guide (2026): Every Common Pod Error URL: https://www.devopsness.com/blog/kubernetes-error-troubleshooting-guide Author: Kiril Urbonas Published: 2026-07-15 Updated: 2026-10-12 Categories: DevOps Tags: Kubernetes, Containers, DevOps, Debugging, Operations Summary: CrashLoopBackOff, ImagePullBackOff, OOMKilled, Pending, NodeNotReady, CreateContainerConfigError, and failing probes, each with what it means, the command that diagnoses it, and the usual fix. --- # Kubernetes Error Troubleshooting Guide (2026): Every Common Pod Error To troubleshoot any Kubernetes pod error, run `kubectl describe pod ` and read the Events at the bottom, then `kubectl logs --previous` if the container crashed. The status name tells you which group you are in: image or config (ImagePullBackOff, CreateContainerConfigError), scheduling (Pending), runtime (CrashLoopBackOff, OOMKilled, probes), or node (NotReady). The status column in `kubectl get pods` is a symptom, not a diagnosis. CrashLoopBackOff only says "this keeps exiting". The cause is almost always in one of three places: pod events, the previous container's logs, or the node's conditions. This guide maps each common error to the place its answer lives, with behavior checked against the Kubernetes 1.37 documentation as of October 2026. ## The four commands that answer most incidents Before matching an error to a section below, collect the evidence: ```bash $ kubectl get pods -o wide # status, restarts, node $ kubectl describe pod # Events: scheduling, pulls, probes, kills $ kubectl logs --previous # output of the container that just died $ kubectl get events --sort-by=.lastTimestamp -A # cluster-wide timeline ``` `describe` covers scheduling, image pulls, probe failures, and OOM kills. `--previous` covers application crashes, because the current container may have only just restarted and have nothing useful to say. The longer kit, including `kubectl debug` with ephemeral containers, is in [kubectl commands for debugging any pod](/blog/kubectl-debugging-commands). ## Kubernetes errors at a glance | Error | What it means | Where to look | Usual cause | |---|---|---|---| | CrashLoopBackOff | Container keeps exiting; kubelet waits longer between restarts | `kubectl logs --previous`, exit code in `describe` | App error, bad config, failing liveness probe | | ImagePullBackOff / ErrImagePull | Node cannot pull the image | Events in `describe` | Wrong tag, private registry without `imagePullSecrets` | | OOMKilled (exit 137) | Container exceeded its memory limit | `Last State` in `describe` | Limit too low or a memory leak | | Pending | No node satisfies the pod's requirements | `FailedScheduling` event | Insufficient CPU or memory, taints, affinity, unbound PVC | | NodeNotReady | Node stopped reporting healthy status | `kubectl describe node` conditions | Kubelet down, disk or memory pressure, network | | CreateContainerConfigError | Pod spec references config that does not exist | Events in `describe` | Missing ConfigMap, Secret, or key | | Probe failures | Liveness or readiness checks fail | `Unhealthy` events | Probe too strict or app slower to start than expected | ## CrashLoopBackOff: the container keeps exiting CrashLoopBackOff means the container started, exited, and the kubelet is now waiting before restarting it. Per the Kubernetes docs, the delay grows exponentially (10s, 20s, 40s, and so on) up to a cap of 300 seconds, and resets after the container runs for 10 minutes without problems. Check the exit code in `describe` and the logs with `--previous`. Exit code 1 is usually the application; 137 means it was killed (often for memory); a liveness probe failure shows up as `Unhealthy` events just before each restart. The full walkthrough is in [How to fix CrashLoopBackOff](/blog/fix-crashloopbackoff). ## ImagePullBackOff and CreateContainerConfigError: the pod spec is wrong ImagePullBackOff means the kubelet could not pull the image and is backing off between attempts, again up to a 300-second limit. The event message names the reason: `manifest unknown` is a wrong tag, `unauthorized` or `pull access denied` is a missing or wrong `imagePullSecrets`, and timeouts point at registry networking. See [How to fix ImagePullBackOff and ErrImagePull](/blog/fix-imagepullbackoff). CreateContainerConfigError is the config twin: the image pulled, but the pod references a ConfigMap, Secret, or key that does not exist in that namespace. The event names the missing object. Create it or fix the reference; covered in [Fixing CreateContainerConfigError](/blog/fix-createcontainerconfigerror). ## OOMKilled: the container hit its memory limit When a container exceeds its memory limit, the kernel's OOM killer ends it with SIGKILL, and Kubernetes reports `Reason: OOMKilled` with exit code 137 (128 plus signal 9). Check `kubectl describe pod` for the last state, then compare the limit against real usage with `kubectl top pod`. Raise the limit if usage is legitimately higher; if memory climbs steadily until the kill, it is a leak, and a higher limit only delays it. Language runtimes need their heap sized below the container limit. Details in [How to fix OOMKilled (exit code 137)](/blog/fix-oomkilled). ## Pending: the scheduler cannot place the pod A Pending pod has not been bound to a node. The `FailedScheduling` event spells out why for each node, for example insufficient CPU on some and an untolerated taint on others. The common causes are resource requests larger than any node's free capacity, taints without matching tolerations, node selectors or affinity rules that match nothing, and PersistentVolumeClaims that cannot bind. Requests count, not actual usage, so an overcommitted request blocks scheduling on an idle cluster. See [why your pod is stuck in Pending](/blog/fix-pod-pending). ## NodeNotReady: the node itself is unhealthy If several pods fail at once on the same node, check the node before the pods. The node controller marks a node unhealthy when it stops reporting for longer than `--node-monitor-grace-period`, which defaults to 50s per the kube-controller-manager reference as of October 2026. Pods get default tolerations of 300 seconds for `not-ready` and `unreachable`, so they stay bound for five minutes before eviction starts. Run `kubectl describe node ` and read the conditions: `MemoryPressure`, `DiskPressure`, or a stopped kubelet are the usual answers. The node-side steps are in [Kubernetes Node NotReady diagnosis and fix](/blog/fix-nodenotready). ## Probes failing: liveness restarts, readiness removes Probe failures look like other errors. A failing liveness probe makes the kubelet kill and restart the container, which surfaces as CrashLoopBackOff. A failing readiness probe never restarts anything; it removes the pod from Service endpoints, which surfaces as 503s or a stuck rollout. The defaults are `periodSeconds: 10`, `timeoutSeconds: 1`, and `failureThreshold: 3`, so a slow endpoint fails liveness after about 30 seconds. Slow-starting apps need a `startupProbe` rather than a long `initialDelaySeconds`. Readiness has subtler traps during deploys, covered in [readiness probes lie during rolling updates](/blog/kubernetes-readiness-probes-lie-during-rolling-updates). ## Questions people ask ### How do I troubleshoot a Kubernetes pod that keeps restarting? Run `kubectl describe pod` and check the last state and exit code, then `kubectl logs --previous` to read the output of the crashed container. Exit code 137 with `OOMKilled` means memory; `Unhealthy` events mean a liveness probe; anything else is usually the application or its config. ### What is the difference between CrashLoopBackOff and ImagePullBackOff? CrashLoopBackOff means the image ran and the process keeps exiting, so the problem is in the application or its config. ImagePullBackOff means the image never ran because the node could not pull it, so the problem is the image name, tag, or registry credentials. ### Why is my Kubernetes pod stuck in Pending? The scheduler cannot find a node that meets the pod's requests and constraints. Read the `FailedScheduling` event: it lists insufficient CPU or memory, untolerated taints, affinity mismatches, or an unbound PersistentVolumeClaim. Lower the requests, add capacity, or fix the constraint. ### How long before Kubernetes evicts pods from a NotReady node? By default about five minutes after the node is detected as unhealthy. The node is marked after the 50-second grace period, and pods carry automatic 300-second tolerations for `not-ready` and `unreachable` taints before they are evicted. ## The call we'd make Train everyone on call to run `describe` and `logs --previous` before touching anything, and to name the error group before guessing at a fix. Then turn each section above into a runbook with links to the detailed guides. Most Kubernetes incidents we see are not novel: they are one of these seven states with a cause the events already printed. ## Sources - [Kubernetes docs: Pod lifecycle and container restart backoff](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/) - [Kubernetes docs: Images and ImagePullBackOff](https://kubernetes.io/docs/concepts/containers/images/) - [Kubernetes API reference: Probe fields and defaults](https://kubernetes.io/docs/reference/kubernetes-api/workload-resources/pod-v1/) - [Kubernetes docs: kube-controller-manager flags](https://kubernetes.io/docs/reference/command-line-tools-reference/kube-controller-manager/) - [Kubernetes docs: Taints and tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/)