Kubernetes Error Troubleshooting Guide (2026): Every Common Pod Error
CrashLoopBackOff, ImagePullBackOff, OOMKilled, Pending, NodeNotReady, CreateContainerConfigError, and failing probes, each with what it means, the command that diagnoses it, and the usual fix.
Key takeaways
- To troubleshoot a Kubernetes error, run kubectl describe pod and read the Events section, then kubectl logs --previous for crashed containers.
- Most errors fall into four groups: the image or config is wrong, the pod cannot be scheduled, the container is killed for memory, or the node itself is unhealthy.
- Each has a short, specific fix.
On this page
To troubleshoot any Kubernetes pod error, run kubectl describe pod <name> and read the Events at the bottom, then kubectl logs <name> --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:
$ kubectl get pods -o wide # status, restarts, node
$ kubectl describe pod <pod> # Events: scheduling, pulls, probes, kills
$ kubectl logs <pod> --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.
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.
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.
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.
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).
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.
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 <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.
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.
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
Terraform Cloud Alternatives — Spacelift, env0, Atlantis, and More
A practical look at Spacelift, env0, Atlantis, and Scalr for teams outgrowing HCP Terraform on price, policy, or OpenTofu support.
Jenkins Pipeline Best Practices in 2026: Builds You Can Trust
A production-focused Jenkins guide: declarative pipelines, shared libraries, ephemeral agents on Kubernetes, scoped credentials, parallel stages, input approvals, post-block rollback and notifications, and Configuration as Code — with copy-paste examples.
More from DevOps
Explore more articles in this category
GitHub Copilot CLI Sandboxing Is GA: What Actually Changed
GitHub made local sandboxing generally available for Copilot CLI on October 7, so the default now restricts the agent instead of trusting it.
The Tensorlake npm Compromise Targeted Your AI Tool Configs
A compromised npm release went after cloud credentials as expected, and local AI coding-assistant config files, which most teams never treated as secrets.
GitLab's New Rate Limits: What to Fix Before Oct 19
GitLab is capping unauthenticated API calls at 60 an hour starting October 19, and the preview windows land before most teams will have noticed.
You might have missed
Evergreen posts worth revisiting.
