Common failure modes and the first thing to check for each.
When something's wrong, start with the same two commands every time:
kubectl describe <kind> <name> # the Events section usually names the cause
kubectl logs <pod> [--previous] # what the app (or the crashed container) saidThen match the symptom below.
| Symptom | Likely cause | First moves |
|---|---|---|
Pod Pending |
no node has room, PVC unbound, or untolerated taint | describe pod → Events; check resources, PVC/StorageClass, and taints/tolerations |
Pod stuck ContainerCreating |
image pull or volume mount failing | describe pod → Events |
ImagePullBackOff |
wrong image name/tag, or private registry without a pull secret | fix the image string; add an imagePullSecret |
CrashLoopBackOff |
container starts then exits repeatedly | logs --previous for the real error; check command/config/env |
OOMKilled (in describe) |
exceeded the memory limit | raise the memory limit or fix the leak |
Pod Running but 0/1 |
readiness probe failing | describe → probe events; fix the health check or app |
Node NotReady |
no/broken CNI, or kubelet down | kubectl get pods -n kube-system (flannel/CNI Running?); see Set Up |
| Service returns nothing | selector matches no Pods (empty endpoints) | kubectl get endpoints <svc>; align Service selector with Pod labels |
| Service name won't resolve | wrong name/namespace, or CoreDNS down | use svc.namespace; check CoreDNS (DNS) |
| Ingress 404 / not reachable | no ingress controller, wrong host/path or ingressClassName |
controller Running? host header matches a rule? (Ingress) |
PVC Pending |
no (default) StorageClass | install/default a provisioner — Volumes |
| Rollout hangs | new Pods never become ready (bad image/probe) | rollout status; rollout undo; then debug |
| Drain blocked | PDB would be violated, or a Pod is unmanaged | kubectl get pdb; check Graceful Shutdown & Disruptions |
API says Forbidden |
RBAC denies this user or ServiceAccount | kubectl auth can-i ...; check Security Basics |
Golden rule: read
describeEvents andlogs --previousbefore deleting or restarting anything — the cause is almost always written there. Full debugging workflow in Debugging.