Troubleshooting Pending PersistentVolumeClaims

💡 Quick Answer: PVC stuck in Pending? Run kubectl describe pvc <name> and check Events. Common causes: no matching StorageClass (kubectl get sc), no available PV for static provisioning, insufficient storage capacity, or volume node affinity conflict. For dynamic provisioning, ensure your cloud provider’s CSI driver is installed and StorageClass has provisioner set correctly.

The Problem

Your PersistentVolumeClaim is stuck in Pending status and your pods can’t start because they’re waiting for storage.

Quick Diagnosis

# Check PVC status
kubectl get pvc

# Get detailed info including events
kubectl describe pvc <pvc-name>

Look at the Events section for clues about why it’s pending.

Common Causes and Fixes

1. No Default StorageClass

Symptoms:

Events:
  Warning  ProvisioningFailed  no persistent volumes available for this claim and no storage class is set

Diagnosis:

# Check if any StorageClass exists and which is default
kubectl get storageclass

# Output shows no (default) marker:
# NAME        PROVISIONER          RECLAIMPOLICY
# standard    kubernetes.io/gce-pd Delete

Fix: Set a default StorageClass:

kubectl patch storageclass standard -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Or specify the StorageClass in your PVC:

spec:
  storageClassName: standard

2. StorageClass Doesn’t Exist

Symptoms:

Events:
  Warning  ProvisioningFailed  storageclass.storage.k8s.io "fast-ssd" not found

Fix: List available StorageClasses and use one that exists:

kubectl get storageclass

3. Volume Binding Mode: WaitForFirstConsumer

Symptoms:

Status:        Pending
Events:        <none>

No events, PVC just sits in Pending.

Diagnosis:

kubectl get storageclass <storageclass-name> -o yaml | grep volumeBindingMode
# volumeBindingMode: WaitForFirstConsumer

Explanation: This is actually normal! The PVC won’t provision until a Pod references it. The volume will be provisioned in the same zone as the Pod.

Fix: Create a Pod that uses the PVC, then it will provision.

4. Insufficient Storage Capacity

Symptoms:

Events:
  Warning  ProvisioningFailed  failed to provision volume: googleapi: Error 403: Quota 'SSD_TOTAL_GB' exceeded

Diagnosis:

# Check current storage usage (cloud provider specific)
# For GCP:
gcloud compute disks list --format="table(name,sizeGb,zone)"

Fix:

• Request less storage
• Delete unused PVCs/PVs
• Request quota increase from cloud provider

5. No Available Persistent Volumes (Static Provisioning)

Symptoms:

Events:
  Warning  ProvisioningFailed  no persistent volumes available for this claim

Diagnosis: You’re using static provisioning but no matching PV exists.

# Check available PVs
kubectl get pv

# Check if any PV matches your PVC requirements
kubectl get pv -o custom-columns=NAME:.metadata.name,CAPACITY:.spec.capacity.storage,ACCESS:.spec.accessModes,STATUS:.status.phase,CLAIM:.spec.claimRef.name

Fix: Create a matching PV:

apiVersion: v1
kind: PersistentVolume
metadata:
  name: my-pv
spec:
  capacity:
    storage: 10Gi
  accessModes:
    - ReadWriteOnce
  persistentVolumeReclaimPolicy: Retain
  storageClassName: ""  # Empty for static provisioning
  hostPath:
    path: /data/my-pv

6. Access Mode Mismatch

Symptoms:

Warning  ProvisioningFailed  no persistent volumes available for this claim

Diagnosis: Your PVC requests an access mode the storage doesn’t support.

# Check what access modes your StorageClass supports
kubectl get storageclass <name> -o yaml

Example: EBS volumes only support ReadWriteOnce, not ReadWriteMany.

Fix: Use a supported access mode:

spec:
  accessModes:
    - ReadWriteOnce  # Instead of ReadWriteMany

7. Node Affinity Conflict

Symptoms:

Warning  ProvisioningFailed  node(s) didn't match node selector

Diagnosis: Zonal storage can’t be attached to pods in different zones.

# Check which zone the PV was created in
kubectl get pv <pv-name> -o yaml | grep -A5 nodeAffinity

Fix:

• Use volumeBindingMode: WaitForFirstConsumer to provision in the pod’s zone
• Use regional storage if available (GKE regional PD, etc.)

8. CSI Driver Not Installed

Symptoms:

Warning  ProvisioningFailed  driver name ebs.csi.aws.com not found

Diagnosis:

# Check installed CSI drivers
kubectl get csidrivers

Fix: Install the required CSI driver:

# Example: AWS EBS CSI Driver
kubectl apply -k "github.com/kubernetes-sigs/aws-ebs-csi-driver/deploy/kubernetes/overlays/stable/?ref=release-1.24"

Debugging Workflow

Step 1: Get PVC Details

kubectl describe pvc <pvc-name>

Step 2: Check Events

kubectl get events --field-selector involvedObject.name=<pvc-name>

Step 3: Check StorageClass

kubectl get storageclass
kubectl describe storageclass <class-name>

Step 4: Check Provisioner Pods

# For CSI drivers, check the controller pods
kubectl get pods -n kube-system | grep csi

# Check logs
kubectl logs -n kube-system <csi-controller-pod> -c csi-provisioner

Step 5: Check Cluster Capacity

# Check node storage
kubectl describe nodes | grep -A5 "Allocatable"

Quick Reference Table

Summary

When debugging Pending PVCs:

1. Always start with kubectl describe pvc
2. Check the Events section for error messages
3. Verify StorageClass exists and is correctly configured
4. Check for capacity/quota issues
5. Verify CSI drivers are installed
6. Consider volumeBindingMode behavior

References

• Kubernetes Storage Troubleshooting
• Debug Pods

📘 Go Further with Kubernetes Recipes

Love this recipe? There’s so much more! This is just one of 100+ hands-on recipes in our comprehensive Kubernetes Recipes book.

Inside the book, you’ll master:

• ✅ Production-ready deployment strategies
• ✅ Advanced networking and security patterns
• ✅ Observability, monitoring, and troubleshooting
• ✅ Real-world best practices from industry experts

“The practical, recipe-based approach made complex Kubernetes concepts finally click for me.”

👉 Get Your Copy Now — Start building production-grade Kubernetes skills today!