Troubleshooting Cheat Sheet
A fast first-command lookup. For the full diagnosis, causes, and fix per symptom, see Troubleshooting.
Pods
| Symptom |
First command |
Likely fix |
Pending |
kubectl describe pod <name> |
Lower requests, add capacity, fix taint/toleration or nodeSelector — details |
ImagePullBackOff / ErrImagePull |
kubectl describe pod <name> |
Fix image tag, add imagePullSecrets — details |
CrashLoopBackOff |
kubectl logs <name> --previous |
Fix app config, tune/add startupProbe — details |
OOMKilled |
kubectl top pod <name> |
Raise resources.limits.memory or fix the leak — details |
Init:CrashLoopBackOff |
kubectl logs <name> -c <init-container> |
Fix the init container's command/dependency wait — details |
Networking
| Symptom |
First command |
Likely fix |
| Service unreachable |
kubectl get endpoints <svc> |
Fix selector/label mismatch or readiness probe — details |
| DNS lookup fails in pod |
kubectl get pods -n kube-system -l k8s-app=kube-dns |
Restart CoreDNS, use FQDN across namespaces — details |
Ingress 404 |
kubectl describe ingress <name> |
Set ingressClassName, fix host/path rule — details |
Ingress 502/503 |
kubectl get endpoints <backend-svc> |
Confirm backend has ready endpoints — details |
| Connection times out, no error |
kubectl get networkpolicy -n <ns> |
Add matching allow rule — details |
Storage
| Symptom |
First command |
Likely fix |
PVC Pending |
kubectl describe pvc <name> |
Set/fix storageClassName, check provisioner — details |
FailedMount |
kubectl describe pod <name> |
Delete stale pod holding a ReadWriteOnce volume — details |
EACCES inside container |
kubectl exec <name> -- id |
Set fsGroup/runAsUser to match volume ownership — details |
Cluster and Nodes
| Symptom |
First command |
Likely fix |
Node NotReady |
kubectl describe node <name> |
Restart kubelet, check CNI pod on that node — details |
Pods Evicted |
kubectl get events -A --field-selector reason=Evicted |
Reclaim disk, set resource requests cluster-wide — details |
kubectl slow/timing out cluster-wide |
kubectl get --raw /healthz |
Check etcd/apiserver health — details |
Rollouts
| Symptom |
First command |
Likely fix |
| Rollout hanging |
kubectl rollout status deployment/<name> |
Check new pod's readiness probe, or kubectl rollout undo |
| Need to revert |
kubectl rollout history deployment/<name> |
kubectl rollout undo deployment/<name> --to-revision=<n> |
Full Troubleshooting Guide · kubectl Cheat Sheet