EC
PVCNotBound
KubernetesWARNINGNotableStorageHIGH confidence

PersistentVolumeClaim is not bound

Production Risk

Stateful applications cannot start without their storage, leading to service outages. If this happens during a recovery, it could lead to data loss if not handled correctly.

What this means

A pod is waiting for a PersistentVolumeClaim (PVC) to be bound, but the PVC itself has not yet been successfully linked to a PersistentVolume (PV). The pod cannot start until the volume is available.

Why it happens
  1. 1No PersistentVolume is available that can satisfy the PVC's requirements (size, access mode, storage class)
  2. 2The StorageClass specified in the PVC does not exist or is misconfigured
  3. 3The underlying storage provisioner is failing to create a PersistentVolume
How to reproduce

A pod that uses a PVC is stuck in a `Pending` or `ContainerCreating` state. Describing the pod shows it is waiting for a PVC to be bound.

trigger — this will error
trigger — this will error
kubectl describe pod my-db-pod

expected output

Events:
  Type     Reason            Age                  From               Message
  ----     ------            ----                 ----               -------
  Warning  FailedScheduling  2m (x12 over 5m)     default-scheduler  0/3 nodes are available: 1 pod has unbound immediate PersistentVolumeClaims.

Fix 1

Describe the PersistentVolumeClaim (PVC)

WHEN To understand why the PVC is not binding

Describe the PersistentVolumeClaim (PVC)
kubectl describe pvc my-pvc

Why this works

The events section of the PVC's description will often contain a message from the storage provisioner explaining why it cannot find or create a suitable PV.

Fix 2

Check available PersistentVolumes (PVs)

WHEN Using manually provisioned volumes

Check available PersistentVolumes (PVs)
kubectl get pv

Why this works

List the existing PVs to see if there is one that matches the PVC's request. Check its capacity, access modes, and status. It may be that no PVs are in the 'Available' state.

Fix 3

Verify the StorageClass

WHEN Using dynamic provisioning

Verify the StorageClass
kubectl get storageclass

Why this works

Ensure that the StorageClass named in the PVC exists and that its provisioner is configured correctly. A typo in the storage class name is a common issue.

What not to do

✕ Manually create a PersistentVolume that does not match the PVC's request

The binding will still fail. The PV's capacity, access modes, and storage class must be compatible with the PVC's request.

Sources
Official documentation ↗

k8s.io/api/core/v1 — PersistentVolumeClaimStatus

Troubleshooting Persistent Volumes ↗

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Kubernetes errors