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.

The pod won't start#

• 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.

The pod won't schedule#

• 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.

The pod dies under load#

• 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.

It runs but nothing can reach it#

• 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.

The mental model#

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.

The call we'd make#

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.