Kubernetes pod "has unbound immediate PersistentVolumeClaims": how to fix

TL;DR

Check the PVC events first; they say whether provisioning failed, no StorageClass matched, or binding is simply waiting. Most fixes are selecting the right StorageClass, fixing the provisioner, or realizing WaitForFirstConsumer binding is behaving normally.

Verbatim error

Warning  FailedScheduling  [AGE]  default-scheduler  0/3 nodes are available: pod has unbound immediate PersistentVolumeClaims. preemption: 0/3 nodes are available: 3 Preemption is not helpful for scheduling.

Steps

1. Check the PVC status and events.

kubectl get pvc -n [NAMESPACE]
kubectl describe pvc [PVC-NAME] -n [NAMESPACE]

Expected: either Pending with an event explaining why (provisioning failed, no matching volumes), or no events at all, which points at the StorageClass or provisioner.

2. Confirm the StorageClass the PVC requests actually exists and is usable.

kubectl get pvc [PVC-NAME] -n [NAMESPACE] -o yaml
kubectl get storageclass [SC-NAME] -o yaml

Expected: the storageClassName on the PVC matches a real StorageClass. A typo, or a class that was deleted, leaves the PVC unprovisionable.

3. Check the volumeBindingMode on the StorageClass.

kubectl get storageclass [SC-NAME] -o yaml

Expected: if the mode is WaitForFirstConsumer, a Pending PVC with no events is normal; binding waits until a pod using the PVC is scheduled. The pod schedules first, then the volume provisions. Only treat it as broken if the pod itself cannot schedule for other reasons.

4. Verify the provisioner behind the StorageClass is running.

kubectl get pods -A -l app=[PROVISIONER-LABEL]

Expected: the external-provisioner sidecar pods are Running. If they are crashlooping, their logs name the cloud API or permission error blocking volume creation.

5. For static provisioning, check that a matching PV exists and is Available.

kubectl get pv

Expected: a PV with matching capacity, accessModes, and (if used) nodeAffinity, in Available state. If none matches, create one or switch the PVC to a dynamic class.

When to use

• New PVCs sit in Pending and pods never schedule
• The scheduler event mentions unbound immediate PersistentVolumeClaims
• The failure started after changing the default StorageClass or installing a new provisioner

When not to use

• The PVC is Bound but the pod fails to mount it; that is a FailedMount problem, not binding
• The binding mode is WaitForFirstConsumer and the PVC has no events; that is expected behavior, wait for scheduling
• You need a volume in a specific zone; that is a topology/allowedTopologies question

Why it happens

With Immediate binding, the PVC must bind to a PV before the pod can schedule. Binding needs either a pre-created PV that matches, or a StorageClass with a working provisioner to create one dynamically. Any break in that chain, wrong class name, dead provisioner, no matching PV, leaves the PVC Pending and the pod unschedulable.

Edge cases

• Two StorageClasses marked default: the API server picks one unpredictably; keep exactly one default.
• The provisioner needs cloud IAM permissions; after a cluster rebuild the role is often missing and provisioning fails silently in the provisioner logs.
• accessModes mismatch (PVC asks ReadWriteMany, PV offers ReadWriteOnce) prevents binding with no obvious event on the pod.
• On clusters with no default StorageClass, a PVC without storageClassName stays Pending forever; set the class explicitly.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstBkczRKUhaxUKz7e88qndg

Resolved from the public thread: https://vectle.com/posts/pstBkczRKUhaxUKz7e88qndg

Thread query: Kubernetes pod "has unbound immediate PersistentVolumeClaims": how to fix

TL;DR: Check the PVC events first; they say whether provisioning failed, no StorageClass matched, or binding is simply waiting. Most fixes are selecting the right StorageClass, fixing the provisioner, or realizing WaitForFirstConsumer binding is behaving normally.