Teams spend most of their Kubernetes time debugging, not building. This is the map to the errors that eat that time: what each one means, how to diagnose it fast, and the fix.
Kubernetes Error Troubleshooting — The Complete Guide
Surveys keep finding the same thing: teams spend the majority of their Kubernetes time troubleshooting rather than shipping. The errors aren't exotic. It's the same dozen states, over and over, each with a name that tells you almost nothing until you've hit it a few times. This guide is the map. For each common failure it says what the state actually means, how to diagnose it in a couple of commands, and where the fix lives.
The universal first move, before any specific error, is to read what the cluster is telling you:
kubectl get pods -o wide
kubectl describe pod <pod> # Events at the bottom are the story
kubectl logs <pod> --previous # Logs from the crashed instance
kubectl get events --sort-by=.lastTimestamp
Nine times out of ten the answer is in describe events or --previous logs. The full command kit is in kubectl commands for debugging any pod.
- CrashLoopBackOff: the container starts, crashes, and Kubernetes keeps restarting it with growing backoff. Almost always an application error or bad config, walked through in fixing CrashLoopBackOff.
- ImagePullBackOff / ErrImagePull: the node can't pull the image: wrong tag, private registry, missing pull secret. See fixing ImagePullBackOff.
- CreateContainerConfigError: a referenced ConfigMap or Secret doesn't exist or a key is missing, covered in CreateContainerConfigError explained.
- Pending: the scheduler can't place it. Insufficient CPU/memory, or a taint/affinity mismatch. Diagnosis in why your pod is stuck in Pending and the scheduler-specific FailedScheduling.
- PersistentVolumeClaim Pending: no volume can satisfy the claim (storage class, zone, capacity), in PVC stuck Pending.
- OOMKilled (exit code 137): the container exceeded its memory limit and the kernel killed it, in fixing OOMKilled. The broader exit-code map is in Kubernetes container exit codes decoded.
- Evicted: the node ran low on memory or disk and the kubelet evicted pods to survive, covered in fixing Evicted pods and node pressure.
- Node NotReady: the node itself dropped out, diagnosed in Node NotReady.
- Service won't connect: selector/label mismatch, wrong port, no ready endpoints, in debugging a Service that won't connect.
- Ingress 502/504: the ingress can't reach a healthy backend, in fixing 502/504 from Ingress.
- DNS resolution failures: CoreDNS or ndots surprises, in fixing DNS resolution in a cluster.
- Too many open files: a file-descriptor limit inside the container, in too many open files in containers.
Almost every Kubernetes failure falls into one of four buckets: it won't start (image/config), it won't schedule (resources/placement), it dies (memory/eviction), or it can't be reached (networking). Naming the bucket from kubectl describe and events turns a scary state into a short checklist. Reliability practices like disruption budgets (Pod Disruption Budgets) and reading memory pressure early (Linux memory pressure with PSI) prevent a chunk of these before they page you.
Learn to read describe events and --previous logs first; they answer most incidents in seconds. Bookmark the four buckets, and when a new error shows up, place it in a bucket before you start guessing. Each linked guide is the fast path for one specific failure. The teams that spend less time troubleshooting aren't luckier; they've turned each of these from a mystery into a runbook.
