Kubernetes PVC Stuck in Pending State Fix

In this tutorial, you'll learn about Kubernetes PVC Stuck in Pending State Fix. We cover key concepts, practical examples, and best practices.

The Problem

Your PersistentVolumeClaim (PVC) stays in Pending state and never binds:

NAME           STATUS    VOLUME   CAPACITY   ACCESS MODES   STORAGECLASS   AGE
my-pvc         Pending                                     2m

The pod that uses this PVC is also stuck in Pending because it cannot mount the volume. The PVC cannot find an available PersistentVolume (PV) that matches its requirements.

Quick Fix

Step 1: Describe the PVC

kubectl describe pvc my-pvc

Events:
  Type     Reason              Age   From                         Message
  ----     ------              ----  ----                         -------
  Warning  ProvisioningFailed  10s   persistentvolume-controller  storageclass.storage.k8s.io "fast-storage" not found

The event tells you the root cause. Common reasons:

• No PV exists that matches the requested storage size and access mode
• StorageClass does not exist or has no provisioner
• storageClassName is misspelled
• Volume binding mode is WaitForFirstConsumer and no pod has been created yet

Step 2: Check available PVs

kubectl get pv

NAME      CAPACITY   ACCESS MODES   RECLAIM POLICY   STATUS      CLAIM   STORAGECLASS   AGE
my-pv     10Gi       RWO            Retain           Available           manual         5d

WRONG -- PVC requests more than any PV offers:

resources:
  requests:
    storage: 100Gi    # no PV has 100Gi available

RIGHT -- match PVC size to available PV capacity:

resources:
  requests:
    storage: 10Gi     # matches my-pv capacity

Step 3: Check access modes match

kubectl get pv my-pv -o yaml | grep accessModes

WRONG -- PVC asks for ReadWriteMany but PV only supports ReadWriteOnce:

accessModes:
  - ReadWriteMany    # PV does not support this

RIGHT -- match the PV's supported access mode:

accessModes:
  - ReadWriteOnce    # matches the PV

Step 4: Verify the StorageClass

kubectl get storageclass

WRONG -- PVC references a StorageClass that does not exist:

storageClassName: fast-ssd    # no StorageClass named fast-ssd exists

RIGHT -- use an existing StorageClass or omit for the default:

storageClassName: standard
# or omit to use the default StorageClass

If using dynamic provisioning, create the missing StorageClass:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/aws-ebs
parameters:
  type: gp3

Step 5: Handle WaitForFirstConsumer binding

If the StorageClass uses volumeBindingMode: WaitForFirstConsumer, the PVC stays Pending until a pod references it:

apiVersion: storage.k8s.io/v1
kind: StorageClass
metadata:
  name: fast-ssd
provisioner: kubernetes.io/aws-ebs
volumeBindingMode: WaitForFirstConsumer   # PVC stays Pending until pod is created

Create the pod that uses the PVC, and the binding completes automatically.

Step 6: Check for reclaim policy conflicts

A PV with ReclaimPolicy: Retain that was previously used may be stuck in Released status:

kubectl get pv

NAME      STATUS     CLAIM          CAPACITY   ACCESS MODES   RECLAIM POLICY   AGE
my-pv     Released   default/old-pvc 10Gi       RWO            Retain          5d

A Released PV cannot be reused until the claim reference is cleared:

kubectl edit pv my-pv
# Remove the claimRef section to reset the PV to Available

Use DodaTech's Storage Inspector to visualize PVC-to-PV binding and diagnose access mode or capacity mismatches.

Prevention

• Define StorageClasses for each storage tier (SSD, HDD, network).
• Create PVs with sizes matching expected PVC requests.
• Use dynamic provisioning with a default StorageClass.
• Set reclaimPolicy: Delete for dynamic volumes.
• Monitor PVC binding status in your CI/CD pipeline.

Common Mistakes with pvc pending

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world K8S code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ