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:

bash.bash

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.