Home / Kubernetes / Kubernetes PVC Stuck Pending Because the StorageClass Does Not Match

Kubernetes

Kubernetes PVC Stuck Pending Because the StorageClass Does Not Match

Fix PersistentVolumeClaims that stay Pending because the referenced StorageClass is missing, has the wrong provisioner, or cannot satisfy the claim requirements.

Published: Jan 23, 202610 min readBy FixWikiHub Editorial Team

Abstract illustration for a troubleshooting knowledge base category.

Introduction

Persistent storage is a fundamental requirement for many Kubernetes workloads, from databases to file-sharing applications. The PersistentVolumeClaim (PVC) mechanism allows users to request storage resources without needing to understand the underlying infrastructure details. When a PVC is created, Kubernetes attempts to either bind it to an existing PersistentVolume (PV) that matches the claim requirements or dynamically provision a new volume through a StorageClass.

A PersistentVolumeClaim remains in the Pending state when Kubernetes cannot satisfy the storage request. The most common reason is that the claim references a StorageClass that doesn't exist in the cluster, the StorageClass provisioner is not functioning correctly, or the claim requests storage characteristics that cannot be fulfilled. Pods that depend on this PVC will also stall, remaining in Pending or ContainerCreating state while waiting for the volume to become available.

Understanding the relationship between PVCs, StorageClasses, and volume provisioning is essential for debugging storage issues. The StorageClass defines how storage is provisioned (the provisioner), what parameters are used (disk type, IOPS, encryption), and whether reclaim policies are applied. When any component of this chain is broken, PVCs cannot progress beyond the Pending state.

Symptoms

When a PVC cannot bind or be provisioned due to StorageClass issues, you will observe these symptoms:

kubectl get pvc shows the PVC in Pending state indefinitely
Pods scheduling fails because the PVC is unbound, showing events like "pod has unbound immediate PersistentVolumeClaims"
kubectl describe pvc reports ProvisioningFailed events or StorageClass-related errors in the event log
The same Kubernetes manifest works in one cluster but fails in another due to different StorageClass availability
PVC status shows "Waiting for a volume to be created either by external provisioner or dynamically provisioned"
Cloud provider controllers log errors about unable to provision volumes

Common error messages from kubectl describe pvc:

bash

Events:
  Type     Reason                Age                From                         Message
  ----     ------                ----               ----                         -------
  Normal   WaitForFirstConsumer  15s                persistentvolume-controller  waiting for first consumer to be created before binding
  Warning  ProvisioningFailed    10s                persistentvolume-controller  storageclass.storage.k8s.io "fast-storage" not found
  Warning  ProvisioningFailed    8s                 csi-controller               failed to provision volume: driver not found

Pod events related to PVC issues:

bash

Events:
  Type     Reason            Age   From               Message
  ----     ------            ----  ----               -------
  Warning  FailedScheduling  15s   default-scheduler  0/3 nodes available: 3 pod has unbound immediate PersistentVolumeClaims.

Common Causes

Several factors prevent PVCs from binding or being provisioned:

1.StorageClass name mismatch: The PVC references a StorageClass name that does not exist in the cluster. This often happens when manifests are copied between environments without adapting to local StorageClass naming conventions.
2.CSI driver or provisioner not installed: A valid StorageClass definition exists, but the CSI driver (Container Storage Interface) that implements the provisioner is not deployed or is unhealthy. Without a functioning provisioner, dynamic provisioning cannot occur.
3.No default StorageClass: The PVC omits storageClassName, expecting a default class to be used, but no StorageClass is marked as default in the cluster. Without a default, Kubernetes cannot determine which provisioner to use.
4.Unsupported access modes: The PVC requests an access mode (like ReadWriteMany for shared NFS access) that the StorageClass's provisioner does not support. Most block storage provisioners only support ReadWriteOnce.
5.Storage capacity unavailable: The PVC requests a size that exceeds available capacity or that the provisioner cannot create. Some provisioners have minimum or maximum size limits.
6.Zone or topology mismatch: The PVC or pod has node selector or topology constraints that conflict with where the StorageClass can provision volumes. For example, requesting storage in a zone where the provisioner has no capacity.
7.Insufficient cloud provider permissions: The CSI driver lacks IAM permissions to create storage resources in the cloud provider. This manifests as provisioning failures even when everything else appears correct.
8.VolumeBindingMode considerations: With WaitForFirstConsumer binding mode, PVCs intentionally stay Pending until a pod consumes them. This is expected behavior but can be confused with actual failures.

Step-by-Step Fix

Follow these steps to diagnose and resolve PVC Pending issues:

Step 1: Inspect PVC events for specific failure reason

The describe output reveals the specific failure:

```bash # Get detailed PVC information and events kubectl describe pvc my-claim -n my-namespace

# Check PVC status field for more details kubectl get pvc my-claim -n my-namespace -o yaml

# Look for specific event messages kubectl get events --field-selector involvedObject.name=my-claim,involvedObject.kind=PersistentVolumeClaim -n my-namespace ```

Key fields to examine in the output: - status.phase: Should show "Pending" - spec.storageClassName: The referenced class name - Events section: Contains ProvisioningFailed or related error messages

Step 2: List and verify StorageClass definitions

Check available StorageClasses and their configurations:

```bash # List all StorageClasses kubectl get storageclass

# Get detailed StorageClass information kubectl get storageclass -o wide

# Check specific StorageClass details kubectl describe storageclass standard

# Verify default StorageClass annotation kubectl get storageclass -o jsonpath='{.items[?(@.metadata.annotations.storageclass\.kubernetes\.io/is-default-class=="true")].metadata.name}' ```

Expected output should show: - All available StorageClass names - The provisioner type for each class - Which class is marked as default (if any)

Step 3: Verify CSI driver/provisioner health

A StorageClass without a working provisioner cannot provision volumes:

```bash # Check CSI driver pods status kubectl get pods -n kube-system | grep -i csi kubectl get pods -n kube-system | grep -i provisioner

# For cloud-specific CSI drivers kubectl get pods -n kube-system | grep aws-ebs # AWS EBS CSI kubectl get pods -n kube-system | grep azure-disk # Azure Disk CSI kubectl get pods -n kube-system | grep gce-pd # GCE PD CSI

# Check CSI driver logs for errors kubectl logs -n kube-system -l app=aws-ebs-csi-controller --tail=50

# Verify CSI driver is registered kubectl get csinodes kubectl get csidrivers ```

Step 4: Create missing StorageClass or use existing one

If the referenced StorageClass is missing, create it or update the PVC:

```bash # Create a new StorageClass (example for AWS EBS CSI) kubectl apply -f - <<EOF apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: fast-storage provisioner: ebs.csi.aws.com parameters: type: gp3 encrypted: "true" volumeBindingMode: WaitForFirstConsumer allowVolumeExpansion: true reclaimPolicy: Delete EOF

# Or update PVC to use existing StorageClass kubectl patch pvc my-claim -n my-namespace -p '{"spec":{"storageClassName":"standard"}}' ```

Step 5: Set default StorageClass if needed

If PVCs omit storageClassName and there's no default:

```bash # Mark a StorageClass as default kubectl patch storageclass standard -p '{"metadata":{"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

# Verify default is set kubectl get storageclass standard -o jsonpath='{.metadata.annotations.storageclass\.kubernetes\.io/is-default-class}' ```

Step 6: Check access mode compatibility

Verify that the requested access mode is supported:

```bash # Check PVC access mode kubectl get pvc my-claim -o jsonpath='{.spec.accessModes[0]}'

# Check what access modes the StorageClass supports kubectl describe storageclass standard | grep -i access

# Common access modes: # ReadWriteOnce (RWO) - Single node read/write (most block storage) # ReadOnlyMany (ROX) - Multiple nodes read only # ReadWriteMany (RWX) - Multiple nodes read/write (requires NFS or shared storage) # ReadWriteOncePod (RWOP) - Single pod read/write (Kubernetes 1.22+)

# If RWX is needed, use NFS or shared filesystem StorageClass kubectl apply -f - <<EOF apiVersion: storage.k8s.io/v1 kind: StorageClass metadata: name: nfs-storage provisioner: nfs.csi.k8s.io parameters: server: nfs-server.example.com share: /export EOF ```

Step 7: Verify cloud provider permissions

Check that CSI driver has necessary permissions:

```bash # For AWS EBS CSI, check IAM role kubectl describe pods -n kube-system -l app=aws-ebs-csi-controller | grep -i "AWS Role"

# Verify AWS permissions by checking controller logs kubectl logs -n kube-system -l app=aws-ebs-csi-controller -c csi-controller | grep -i error

# Required AWS permissions for EBS CSI: # ec2:CreateVolume, ec2:DeleteVolume, ec2:AttachVolume, ec2:DetachVolume # ec2:DescribeVolumes, ec2:DescribeInstances, ec2:ModifyVolume ```

Step 8: Handle WaitForFirstConsumer mode

If StorageClass uses WaitForFirstConsumer, create a pod that uses the PVC:

yaml

# Create a pod to trigger provisioning
apiVersion: v1
kind: Pod
metadata:
  name: test-pod
spec:
  containers:
  - name: test
    image: busybox
    command: ["sleep", "3600"]
    volumeMounts:
    - name: data
      mountPath: /data
  volumes:
  - name: data
    persistentVolumeClaim:
      claimName: my-claim

bash

kubectl apply -f test-pod.yaml
kubectl get pvc my-claim -w  # Watch PVC status change

Verification

After fixing the issue, verify the PVC binds correctly:

```bash # Check PVC status kubectl get pvc my-claim -n my-namespace

# Expected output showing Bound status: # NAME STATUS VOLUME CAPACITY ACCESS MODES STORAGECLASS # my-claim Bound pvc-12345678-90ab-cdef-1234-567890abcdef 10Gi RWO standard

# Verify the bound PV kubectl get pv | grep my-claim

# Check that dependent pods start running kubectl get pods -n my-namespace

# Verify volume is accessible in pod kubectl exec -it pod-using-pvc -- df -h /data kubectl exec -it pod-using-pvc -- ls -la /data ```

Prevention

To prevent PVC StorageClass issues:

1.Standardize StorageClass naming: Use consistent StorageClass names across development, staging, and production clusters. Document naming conventions and include them in project setup guides.
2.Monitor CSI controller health: CSI drivers are critical infrastructure components. Set up alerts for CSI controller pod failures, restarts, or provisioning failures.

yaml

# Prometheus alert example
- alert: CSIControllerDown
  expr: up{app=~".*csi.*controller"} == 0
  for: 5m
  severity: critical

1.Document default StorageClass behavior: Clearly document whether applications should rely on default StorageClass or specify explicit class names. Include this in deployment guides.
2.Validate manifests in CI: Before deploying to production, validate PVC configurations against cluster StorageClass availability in CI pipelines.

bash

# CI validation script
kubectl get storageclass -o name | grep -q "$(grep storageClassName deployment.yaml)" || \
  echo "ERROR: StorageClass not found"

1.Use infrastructure as code: Define StorageClasses in Terraform, Pulumi, or GitOps repositories alongside application manifests. This ensures StorageClasses exist before PVCs reference them.
2.Pre-provision volumes for special cases: For large volumes, specific performance requirements, or pre-existing data, pre-provision PVs rather than relying on dynamic provisioning.
3.Test storage provisioning regularly: Include storage provisioning tests in cluster health checks. Create and delete test PVCs to verify the provisioning pipeline works.

[Fix Envoy Rate Limit Configuration with envoyproxy/ratelimit](envoyproxy-ratelimit-configuration-guide)
[Fix Fix Argocd App Not Syncing Issue in Kubernetes](fix-argocd-app-not-syncing)
[Fix Fix Argocd Sync Conflict Issue in Kubernetes](fix-argocd-sync-conflict)
[Fix ArgoCD Sync Timeout](fix-argocd-sync-timeout)
[How to Fix Cilium Identity Exhaustion and Endpoint Allocation Failed](fix-cilium-identity-exhaustion)

Was this guide helpful?

Related search paths

People also search for

If the symptom is close but not identical, these search paths usually surface the right neighboring fixes faster than scrolling the full archive.

Kubernetes PVC Stuck Pending Kubernetes PVC Stuck Pending Kubernetes Kubernetes PVC Stuck Pending troubleshooting Kubernetes PVC Stuck Pending fix Fix PersistentVolumeClaims that stay Pending because the referenced StorageClass is missing, has the wrong provisioner, or cannot satisfy the claim requirements Kubernetes Fix PersistentVolumeClaims that stay Pending because the referenced StorageClass is missing, has the wrong provisioner, or cannot satisfy the claim requirements

Explore Related Topics

Browse Guides from Other Categories

Discover troubleshooting guides from related categories to expand your knowledge.

FAQ

Kubernetes Troubleshooting FAQs

Common questions about troubleshooting and preventing similar issues

How do I know if this kubernetes-errors troubleshooting guide applies to my situation?

This guide is designed for kubernetes-errors issues. If you're experiencing similar symptoms described in the article, follow the step-by-step instructions. Start with the most common causes and work through the diagnostic process.

Is it safe to follow these kubernetes-errors troubleshooting steps?

Yes, all steps are designed to be safe and non-destructive. We recommend creating backups before making significant changes and testing each step before proceeding to the next.

How long does it typically take to resolve this type of kubernetes-errors issue?

Most kubernetes-errors issues can be resolved within 30 minutes to 2 hours, depending on the complexity and root cause. Follow the troubleshooting flow to identify and fix the problem efficiently.

How can I prevent this kubernetes-errors issue from happening again?

Regular maintenance, monitoring, and following best practices for kubernetes-errors configuration can help prevent recurrence. Consider implementing automated checks and alerts for early detection.

Written by

FixWikiHub Editorial Team

Our editorial team consists of experienced DevOps engineers, systems administrators, and cloud architects with hands-on experience in production environments across AWS, Azure, GCP, and on-premises infrastructure.

Every guide undergoes technical review for accuracy and is updated when software versions, commands, or best practices change.

Last updated: Jan 23, 2026

About our team

Important Notice

Disclaimer & Safety Guidelines

The troubleshooting steps in this guide are provided for educational and informational purposes. Before applying any changes to production systems:

Test in a staging environment first — Always verify commands and configurations in a non-production environment before deploying to live systems.
Create backups — Ensure you have current backups of databases, configurations, and critical files before making changes.
Understand the impact — Review how each step may affect your specific environment, dependencies, and users.
Consult official documentation — This guide supplements, but does not replace, official vendor documentation and best practices.

FixWikiHub is not responsible for any damages arising from the use of this content. See our Terms of Use for more information.

Resources

Official Documentation & Further Reading

For authoritative information, consult the official documentation for the technologies discussed in this guide. Our troubleshooting content supplements, but does not replace, vendor documentation.

AWS Documentation — Official Amazon Web Services guides and API references
Kubernetes Documentation — Official Kubernetes documentation
Nginx Documentation — Official Nginx web server documentation
Apache Documentation — Official Apache HTTP Server documentation
Docker Documentation — Official Docker container documentation

Kubernetes PVC Stuck Pending Because the StorageClass Does Not Match

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Inspect PVC events for specific failure reason

Step 2: List and verify StorageClass definitions

Step 3: Verify CSI driver/provisioner health

Step 4: Create missing StorageClass or use existing one

Step 5: Set default StorageClass if needed

Step 6: Check access mode compatibility

Step 7: Verify cloud provider permissions

Step 8: Handle WaitForFirstConsumer mode

Verification

Prevention

People also search for

Browse Guides from Other Categories

WordPress

SSL

DNS

Kubernetes Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading

Kubernetes PVC Stuck Pending Because the StorageClass Does Not Match

Introduction

Symptoms

Common Causes

Step-by-Step Fix

Step 1: Inspect PVC events for specific failure reason

Step 2: List and verify StorageClass definitions

Step 3: Verify CSI driver/provisioner health

Step 4: Create missing StorageClass or use existing one

Step 5: Set default StorageClass if needed

Step 6: Check access mode compatibility

Step 7: Verify cloud provider permissions

Step 8: Handle WaitForFirstConsumer mode

Verification

Prevention

Related Articles

People also search for

Share this guide

More Kubernetes Troubleshooting Guides

Browse Guides from Other Categories

Kubernetes Troubleshooting FAQs

FixWikiHub Editorial Team

Disclaimer & Safety Guidelines

Official Documentation & Further Reading