# Troubleshooting

`kubectl` output is rarely the actual problem — `CrashLoopBackOff`, `Pending`, and `503` are symptoms, not root causes. This page is the methodology and the diagnostic toolkit; the pages after it work through each failure category symptom by symptom, with the real diagnosis and fix for each.

## The Diagnostic Toolkit

| Command | What it actually tells you |
| --- | --- |
| `kubectl get events --sort-by=.metadata.creationTimestamp -A` | The chronological story of what the cluster tried to do and where it gave up |
| `kubectl describe <kind> <name>` | Conditions, events, and the exact scheduling/admission reason — the single most useful command for "why" |
| `kubectl logs <pod> [-c container] [--previous]` | What the application itself said, including the last thing it printed before it died |
| `kubectl get <kind> -o yaml` | The actual applied spec and live status, not what you think you applied |
| `kubectl top nodes` / `kubectl top pods` | Real-time resource pressure — requires the metrics server |
| `kubectl exec -it <pod> -- sh` or `kubectl debug` | A shell inside (or attached to) the failing container, for anything logs don't explain |
| `kubectl get --raw='/readyz?verbose'` / node `.status.conditions` | Control-plane and node health, one layer below the workload |

## The Decision Tree

```
flowchart TD
    A[Something is broken] --> B{Pod stuck Pending,\ncrashing, or not\npulling its image?}
    B -->|Yes| C[Pod startup —\nsee Pod Startup\nErrors triage]
    B -->|No| D{Traffic not\nreaching the pod?}
    D -->|Yes| E[Networking — see\nNetworking and Service\nProblems]
    D -->|No| F{PVC pending or\nvolume mount failing?}
    F -->|Yes| G[Storage — see\nStorage Problems]
    F -->|No| H{Node NotReady or\ncontrol plane\nunresponsive?}
    H -->|Yes| I[Cluster/node — see\nCluster and Node Problems]
    H -->|No| J[Re-run kubectl describe\nand read events —\nthe cause is usually there]
```

## Read in this order

1. [Pod Startup Errors: Triage Guide](<https://computecentral.in/kubernetes/troubleshooting/01-pod-scheduling-and-startup-problems/index.md>)

   - [Pod stuck in Pending](<https://computecentral.in/kubernetes/troubleshooting/pod-pending/index.md>)
   - [ImagePullBackOff and ErrImagePull](<https://computecentral.in/kubernetes/troubleshooting/imagepullbackoff/index.md>)
   - [CrashLoopBackOff](<https://computecentral.in/kubernetes/troubleshooting/crashloopbackoff/index.md>)
   - [OOMKilled (exit code 137)](<https://computecentral.in/kubernetes/troubleshooting/oomkilled/index.md>)
   - [Init:CrashLoopBackOff and stuck init containers](<https://computecentral.in/kubernetes/troubleshooting/init-container-failures/index.md>)
2. [Networking and Service Problems](<https://computecentral.in/kubernetes/troubleshooting/02-networking-and-service-problems/index.md>)
3. [Storage Problems](<https://computecentral.in/kubernetes/troubleshooting/03-storage-problems/index.md>)
4. [Cluster and Node Problems](<https://computecentral.in/kubernetes/troubleshooting/04-cluster-and-node-problems/index.md>) — including pods stuck in `Terminating`

## Next

Continue to [Interview Preparation](<https://computecentral.in/kubernetes/interview-prep/index.md>).
