# kubectl troubleshooting cheat sheet

> kubectl troubleshooting cheat sheet: the describe/logs/events/exec debug loop, rollout commands, and what CrashLoopBackOff, Pending and ImagePullBackOff mean.

- Page URL: https://itinsighthub.com/kubectl/troubleshooting/
- Markdown variant of this page: append `?format=md` to any URL on this site or send `Accept: text/markdown`.
- Full site index for AI assistants: https://itinsighthub.com/llms.txt
- Full site export: https://itinsighthub.com/llms-full.txt

# 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 August 22, 2026

## 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 :** 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/:** waits for and reports a rollout's progress

## The status-code field guide

*What the pod status actually means, and the usual fix*

| Status | Meaning | Usual fix |
| --- | --- | --- |
| Pending | the pod cannot be scheduled (no resources, no node matches, or PVC not bound) | check node capacity, node selectors and storage in describe |
| ContainerCreating | the container is pulling its image or setting up | if it stalls, check image name/registry and network egress |
| ImagePullBackOff | the image cannot be pulled (bad name/tag, private registry auth) | fix the image reference or add an imagePullSecret |
| CrashLoopBackOff | the container starts, exits, and Kubernetes keeps restarting it | read logs --previous to see the exit error |
| ErrImagePull | same family as ImagePullBackOff — a pull error | as above |
| Completed | the container finished successfully and exited (normal for a Job) | expected — do nothing |
| OOMKilled | the container exceeded its memory limit and was killed | raise 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

- [Debugging Kubernetes](https://kubernetes.io/docs/tasks/debug/) — the official troubleshooting guides.
- [Debugging Pods](https://kubernetes.io/docs/tasks/debug/debug-application/debug-pods/) — pod-level failure patterns and fixes.

## 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 .

## Related tools

- [IPv4 subnet calculator](https://itinsighthub.com/subnet-calculator/) — break any CIDR block into network, range, broadcast and usable hosts.
- [IP range to CIDR](https://itinsighthub.com/ip-range-to-cidr/) — turn an arbitrary address range into its minimal covering CIDR blocks.
- [VLSM calculator](https://itinsighthub.com/vlsm-calculator/) — split a block into right-sized subnets by host requirements.

---

© 2026 ITInsightHub · [About](https://itinsighthub.com/about/) · [Contact](https://itinsighthub.com/contact/) · [Privacy](https://itinsighthub.com/privacy/)