ITInsightHub

kubectl troubleshooting cheat sheet

When a pod misbehaves, work the same loop every time, from outside in: get to see state, describe to see why (its Events are the clue), logs to hear what the app said, and exec to look around inside. Jumping straight to a fix without these four steps is how you waste an afternoon.

Most pod failures collapse into a handful of statuses with known causes, collected in the field guide at the bottom.

Published

The debug loop

The four steps, in order
# 1. What state is everything in?
kubectl get pods -o wide

# 2. Why? — read the Events section at the bottom
kubectl describe pod <pod-name>

# 3. What did the app print before it failed?
kubectl logs <pod-name> --previous

# 4. Look around inside
kubectl exec -it <pod-name> -- sh

Supporting commands for specific symptoms

kubectl get events --sort-by=.metadata.creationTimestamp
cluster events in time order — the shared breadcrumb trail
kubectl describe deployment <name>
rollout config plus the deployment's own events
kubectl get pods -o wide
adds node and IP — spots pods stuck on the wrong node
kubectl top pods
CPU/memory per pod, to catch resource exhaustion (needs Metrics Server)
kubectl rollout status deployment/<name>
waits for and reports a rollout's progress

The status-code field guide

What the pod status actually means, and the usual fix
StatusMeaningUsual fix
Pendingthe pod cannot be scheduled (no resources, no node matches, or PVC not bound)check node capacity, node selectors and storage in describe
ContainerCreatingthe container is pulling its image or setting upif it stalls, check image name/registry and network egress
ImagePullBackOffthe image cannot be pulled (bad name/tag, private registry auth)fix the image reference or add an imagePullSecret
CrashLoopBackOffthe container starts, exits, and Kubernetes keeps restarting itread logs --previous to see the exit error
ErrImagePullsame family as ImagePullBackOff — a pull erroras above
Completedthe container finished successfully and exited (normal for a Job)expected — do nothing
OOMKilledthe container exceeded its memory limit and was killedraise limits or fix the memory leak

Rolling back a bad change

Inspect and undo a rollout
# History of a deployment's rollouts
kubectl rollout history deployment/nginx

# Undo the last change
kubectl rollout undo deployment/nginx

# Undo to a specific revision
kubectl rollout undo deployment/nginx --to-revision=2

# Restart pods to force a fresh pull/reconcile
kubectl rollout restart deployment/nginx
rollout undo only works for changes that went through the Deployment's rollout history — direct edits to a pod are not tracked. If a rollout is stuck (old and new pods both running, status shows no progress), kubectl rollout status and describe deployment will show why, usually a failing readiness probe or insufficient resources for the new replicas.

References

FAQ

What does CrashLoopBackOff mean?

The container started, exited (crashed or completed), and Kubernetes has entered an exponential back-off restart loop. The fix is almost always in the logs: kubectl logs --previous shows the last output before the crash. Common causes are a bad command, a missing dependency, or a failing readiness/liveness probe.

What does Pending mean for a pod?

The pod has not been scheduled onto a node yet. Reasons include insufficient CPU/memory on every node, node selectors or taints that no node satisfies, or a PersistentVolumeClaim that has not bound. kubectl describe pod lists the exact scheduling events and messages.

What does ImagePullBackOff mean?

Kubernetes cannot pull the container image. The image name or tag may be wrong, the registry may be unreachable, or a private registry needs credentials via an imagePullSecret. Check the image field in the pod spec and the describe output for the exact pull error.

How do I see what my container printed before it crashed?

kubectl logs --previous fetches the logs of the previous container instance — the one that just exited. Without --previous, kubectl logs shows the current (restarting) container, which may not have produced output yet. For multi-container pods, add -c .