☸️
Kubernetes Error
Kubernetes Pod Stuck in Pending State
The pod has been accepted by the cluster but the scheduler can't find a node with enough resources (or matching constraints) to place it on.
What This Error Means
A pod in Pending state has been created in the Kubernetes API but hasn't been scheduled onto any node yet — the scheduler is either still deciding, or has determined no node currently satisfies the pod's resource requests or scheduling constraints.
Why It Occurs
Most commonly the cluster doesn't have enough available CPU/memory on any single node to satisfy the pod's resource requests, or the pod has node affinity/taints/tolerations constraints that no available node satisfies, or a required PersistentVolumeClaim can't be bound.
Symptoms
- ⚠ `kubectl get pods` shows the pod stuck in Pending, sometimes indefinitely
- ⚠ No container ever starts, unlike CrashLoopBackOff where at least a container attempts to run
Common Causes
- • Insufficient CPU/memory available across all nodes to satisfy the pod's resource requests
- • Node affinity, taints, or nodeSelector constraints that no current node matches
- • A PersistentVolumeClaim the pod depends on can't be bound to an available PersistentVolume
- • The cluster is at its maximum pod count per node or overall
How to Fix It
- Check the exact reason: `kubectl describe pod pod-name` — the Events section explicitly states why scheduling failed (e.g. "Insufficient cpu", "node(s) had taint...")
- If resource-constrained, either reduce the pod's resource requests to a realistic value, or scale the cluster (add nodes / larger nodes)
- If a nodeSelector/affinity rule is too restrictive, verify at least one node actually has the required labels: `kubectl get nodes --show-labels`
- If a PVC is unbound, check `kubectl get pvc` and `kubectl get pv` to see if a matching PersistentVolume exists or needs to be provisioned
| Command | Purpose |
|---|---|
| kubectl describe pod pod-name | See the exact scheduling failure reason |
| kubectl get nodes --show-labels | Check whether any node satisfies a nodeSelector/affinity constraint |
| kubectl get pvc | Check if a required PersistentVolumeClaim is unbound |
Advertisement
Verification
- ✓ `kubectl get pods` shows the pod moving from Pending into ContainerCreating and then Running
Prevention
- → Set resource requests based on realistic measured usage, and monitor overall cluster capacity headroom proactively
- → Document and communicate any node affinity/taint requirements clearly when they're genuinely required, since they're a common source of confusing Pending states