Skip to content

⏳ Troubleshooting Pending Pods

A Pod stuck in Pending state means it cannot be scheduled to a node. This is one of the most common issues in Kubernetes.

🔍 Check Pod Status

kubectl get pods
kubectl describe pod <pod-name>

Look at:

  • Events section
  • Scheduling conditions
  • Resource requests vs available node capacity

🔎 Common Causes of Pending State

1. Insufficient Resources

  • Pod requests more CPU/memory than any node can provide
resources:
  requests:
    memory: "8Gi"
    cpu: "4"

Fix: Reduce resource requests or add larger nodes.

2. No Matching Node Selectors

nodeSelector:
  disktype: ssd

Fix: Ensure nodes have matching labels or remove selector.

3. Taints Without Tolerations

  • Node is tainted but Pod doesn’t tolerate it
kubectl describe node <node>

Fix: Add tolerations to Pod spec if appropriate.

4. Affinity Rules Not Satisfied

  • Pod's nodeAffinity or podAffinity can’t be satisfied

Fix: Loosen constraints or ensure required nodes/pods exist.

5. PVC Not Bound

  • Pod references a PersistentVolumeClaim that isn't yet bound
kubectl get pvc

Fix: Ensure storage class and volume are properly configured.

6. Quota or LimitRange Restrictions

  • Namespace has a ResourceQuota or LimitRange blocking the pod
kubectl describe quota -n <ns>
kubectl describe limitrange -n <ns>

Fix: Adjust quota or resource requests.

7. Unschedulable Nodes

  • Nodes are NotReady or cordoned
kubectl get nodes

Fix: Uncordon or fix failing nodes.

🧪 Debugging Steps

  1. Describe the Pod:
kubectl describe pod <pod-name>

  1. Look for event reasons like:

  2. FailedScheduling

  3. 0/3 nodes are available: ...

  4. Describe nodes if relevant:

kubectl describe node <node-name>

🧠 Tips

  • Use kubectl get events --sort-by=.metadata.creationTimestamp
  • Always define reasonable requests and limits
  • Use kubectl top nodes to inspect real-time usage
  • Use --dry-run=client and kubectl explain to validate specs before applying

✅ Summary

Cause Symptom Fix
Too much CPU/memory No nodes available Reduce requests or add nodes
Missing nodeSelector match Scheduler can’t find suitable node Add labels to nodes or change selector
Taints without toleration Pod blocked by taint Add tolerations to Pod
PVC not bound Waiting for volume Check storage classes and PVC status
Affinity mismatch Constraints too strict Loosen or fix affinity rules

A Pending pod is a scheduling issue — check your constraints, resources, and node conditions carefully.