How to Fix Kubernetes Pod Pending State

In this tutorial, you'll learn about How to Fix Kubernetes Pod Pending State. We cover key concepts, practical examples, and best practices.

The Problem

You deploy a pod and it stays in Pending:

NAME                     READY   STATUS    RESTARTS   AGE
my-pod-6b4c9f8d7-abc12   0/1     Pending   0          5m

Describing the pod shows:

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  2m    default-scheduler  0/3 nodes are available: 1 Insufficient cpu, 2 Insufficient memory.

The pod cannot be scheduled because no node meets its resource requirements or there are persistent volume claims that cannot be bound.

Quick Fix

Step 1: Describe the pod

kubectl describe pod my-pod-6b4c9f8d7-abc12

The Events section shows why scheduling is failing.

Step 2: Check node resources

kubectl get nodes
kubectl describe nodes

Look for pressure conditions:

Conditions:
  Type              Status
  MemoryPressure    True
  DiskPressure      False
  PIDPressure       False

Step 3: Reduce resource requests

Edit your deployment to lower resource requests:

kubectl edit deployment my-deployment

resources:
  requests:
    memory: "128Mi"
    cpu: "100m"
  limits:
    memory: "256Mi"
    cpu: "200m"

Step 4: Remove node selectors or taints

Check if a node selector is preventing scheduling:

kubectl get pod my-pod-6b4c9f8d7-abc12 -o json | jq '.spec.nodeSelector'

Remove the selector if it does not match any node.

Alternative Solutions

Add more nodes to the cluster:

# On cloud providers
kubectl scale nodegroup --replicas=3

# On Minikube
minikube node add

Use kubectl describe for Detailed Diagnostics

kubectl describe pod <pod-name>
# Events:
#   Type     Reason     Age   From     Message
#   ----     ------     ----  ----     -------
#   Warning  BackOff    5m    kubelet  Back-off restarting failed container

The Events section at the bottom of kubectl describe output is the most valuable diagnostic tool. It shows a chronological log of scheduling failures, image pull errors, and container crashes.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Set realistic resource requests based on actual usage.
• Use cluster autoscaling for variable workloads.
• Monitor cluster capacity with kubectl top nodes.