Library Play · 10, 20 or all 46 scenariosDiagnose the clusterRead the evidence, find the cause, pick the first fix.Play
Kubernetes errors
Explained visually. You watch the cluster: which component fails, how it unfolds, then a 60-second diagnosis and the fix.
Symptom picker
Which error is it?
1 · What is going wrong?
Pod won't start
It never reaches Running.
- ConfigMap / Secret issuesA container cannot be created because a ConfigMap or Secret it refers to is missing, or it keeps running with old values after an update.Breaks at: kubelet · kube-apiserver
- ImagePullBackOffThe node cannot download the container image, so the container never starts. The kubelet keeps retrying, more and more slowly.Breaks at: Image registry · kubelet
- Pending podThe pod has been accepted but no node can take it, so it has not been scheduled and nothing is running.Breaks at: Scheduler
Pod keeps restarting
It starts, dies and starts again.
- CrashLoopBackOffThe container starts, exits, and is restarted over and over, with a longer wait before each new attempt.Breaks at: Your container · kubelet
- Liveness probe failureThe kubelet decided the container was stuck, killed it and started it again. Often the container was fine and the check was wrong.Breaks at: kubelet · Your container
- OOMKilledThe container used more memory than its limit, and the Linux kernel killed it. Exit code 137.Breaks at: Linux kernel · Your container
No traffic
Pods look fine, but requests don't arrive.
- DNS resolution failurePods cannot turn names into addresses, or only slowly, because queries to CoreDNS fail or time out.Breaks at: CoreDNS · Your container
- NetworkPolicy blocking trafficA NetworkPolicy selects the pod, and the connection you need is not on its allow-list, so packets are silently dropped.Breaks at: CNI plugin · Your container
- Readiness probe failureThe pod is Running but not Ready, so the Service has stopped sending it traffic. The container is not restarted.Breaks at: Your container · Service
- Service has no endpointsPods are Running, but the Service in front of them has an empty endpoint list, so connections to it fail.Breaks at: Service · kube-proxy
Slow
It works, with latency you can't explain.
Cluster / node
A whole machine is in trouble.
Storage
A volume won't bind, attach or mount.
Scaling
Replicas don't follow the load, or a rollout is stuck.
- Deployment rollout failureA rolling update has stopped partway: the new pods never become Ready, so the old ones are never removed.Breaks at: Your container · Controller manager
- HPA not scalingLoad rises but the HorizontalPodAutoscaler leaves the replica count where it is.Breaks at: HPA controller · metrics-server
Things people mix up
The same failure, played side by side, so the difference shows in a few seconds.
- Connection refused vs timeout in KubernetesRefused: something answered “no” straight away. Timeout: nothing answered at all, and the caller gave up waiting.
- CrashLoopBackOff vs ImagePullBackOffCrashLoopBackOff: the container starts and then exits. ImagePullBackOff: the image never arrives, so the container never starts.
- OOMKilled vs EvictedOOMKilled: one container broke its own limit, and the kernel killed it. Evicted: the node ran short, and the kubelet removed a whole pod.
- Pending vs ContainerCreatingPending: no node has been chosen, so nothing is even trying to start it. ContainerCreating: a node has it, and the kubelet is still getting things ready.
- Readiness vs liveness vs startup probesReadiness decides whether a pod gets traffic. Liveness decides whether its container is restarted. Startup holds the other two back until the app has started.
Guides
Cheat sheets and walkthroughs that tie the error pages together.
- Cheat sheetEssential kubectl troubleshooting commandsThe kubectl commands worth knowing by heart for production support, what each one tells you, and which problem it leads to.
- WalkthroughProduction incident: a Spring Boot API becomes slowAPI latency goes from 200ms to 5 seconds while every pod looks healthy. Follow the investigation step by step, command by command.
- Questions and answersSenior-level Kubernetes interview questionsTwelve Kubernetes troubleshooting questions asked of senior backend engineers, each with a short answer and a link to the animated explanation.
Practise: diagnose the cluster
Read the terminal, watch the animation, pick the error and the first fix.