Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

Kubernetes PVC stuck in Pending: "no persistent volumes available for this claim and no storage class is set"

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

A PersistentVolumeClaim (PVC) that stays Pending and shows the event no persistent volumes available for this claim and no storage class is set has no StorageClass and no existing PersistentVolume that matches it. Read the claim, the StorageClasses and the volumes first. Then either mark one StorageClass as the default, so claims without a class can be provisioned, or give the claim a class or a matching volume.

What the symptom means

The text of that event comes from the persistent volume controller's source code (release tag v1.34.0), which emits it as a FailedBinding event of type Normal, not Warning. It is the branch taken when the claim has no storage class and no volume matches. The Persistent Volumes page says "Claims will remain unbound indefinitely if a matching volume does not exist."

A claim without storageClassName is handled in one of two ways. If the DefaultStorageClass admission plugin is on and a default StorageClass exists, the default is used. The StorageClass page says that if no StorageClass is marked as default, Kubernetes cannot apply that defaulting. The claim is created as defined, and its storageClassName stays unset until a default becomes available.

Other Pending claims show other events, so match the event before you change anything. These texts also come from the same source code (release tag v1.34.0), and some of them are built from formats whose variable part is named below:

  • waiting for first consumer to be created before binding comes from a class with volumeBindingMode: WaitForFirstConsumer. Binding is delayed until a pod uses the claim. This is normal until then. Once a pod that uses the claim is waiting to be scheduled, the source instead emits waiting for pod %s to be scheduled for one pod, or waiting for pods %s to be scheduled for several, where %s is the pod's name or the pod names joined by commas.
  • The source format is Waiting for a volume to be created either by the external provisioner '%s' or manually by the system administrator. and the %s is the provisioner's name. It means a class named a provisioner and the claim is waiting for it. The message goes on to say to verify that the provisioner is running and correctly registered.
  • The source format is volume %q already bound to a different claim. and the %q is the volume's name in quotation marks. It is a Warning that appears when the claim asks for a specific volume by volumeName and another claim holds it.

Likely causes

Cause What you see How to confirm
No default StorageClass and the claim names no class Event no persistent volumes available for this claim and no storage class is set kubectl get storageclass shows no (default) marker; the claim's YAML has no storageClassName
Claim sets storageClassName: "" explicitly Same event; a later default class does not change the claim The claim's YAML shows an empty storageClassName; the Storage Classes page says such a claim is not updated when a default appears
Static volume does not match the claim Claim Pending although volumes exist kubectl get pv: capacity smaller than the request, different access mode, different class, or a label selector that does not match
Class named but no working provisioner Event Waiting for a volume to be created either by the external provisioner The class's provisioner field, and whether that provisioner's pods run
Class uses kubernetes.io/no-provisioner (local volumes) Claim waits and no volume is created The StorageClass page says local volumes do not support dynamic provisioning, so a volume must be created in advance
WaitForFirstConsumer and no pod yet, or the pod sets nodeName Event waiting for first consumer to be created before binding The StorageClass page says that with nodeName set the scheduler is bypassed and the claim remains Pending

Prove the cause before changing anything

All of these are read-only.

1. Read the claim's status and events.

kubectl get pvc -n shop
kubectl describe pvc <claim-name> -n shop

The Events section holds the message that selects the row in the table above.

2. Read what the claim asks for.

kubectl get pvc <claim-name> -n shop -o yaml

Note spec.storageClassName (absent, empty or a name), spec.accessModes, spec.resources.requests.storage and spec.volumeName. A missing storageClassName and an empty one behave differently, as described above.

3. List the StorageClasses.

kubectl get storageclass

The change-default page shows the default class marked (default) in this listing. No marker means no default.

4. List the volumes and read their phase.

kubectl get pv
kubectl describe pv <volume-name>

The volumes page lists the phases: Available is a free volume not yet bound, Bound is bound to a claim, Released means the claim was deleted but the storage is not yet reclaimed, and Failed means automated reclamation failed. Only an Available volume with a matching class, size and access mode can bind. A 50Gi volume does not match a claim for 100Gi, as the page's own example says.

Fix

Fix the cause the event and the three listings showed.

Mark one StorageClass as the default

Use this only when claims without a class should be provisioned from that class. First save the class, which records its present annotations:

kubectl get storageclass fast -o yaml > /root/storageclass-fast-2026-11-22.yaml

Risk: the patch below marks the fast StorageClass as the default. Every new claim without a class is provisioned from it, and the Storage Classes page says the control plane updates existing claims with no storageClassName to the new default. If more than one class is marked default, the most recently created default is used.

The annotation is storageclass.kubernetes.io/is-default-class, as in the change-default page:

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

To undo it, set the annotation back to the value in the saved file. The page says any value other than true, or no annotation at all, counts as not default. If the saved file had no annotation, remove it again with a JSON merge patch. The kubectl patch reference lists merge as one patch type, and RFC 7386 says "Null values in the merge patch are given special meaning to indicate the removal of existing values in the target."

kubectl patch storageclass fast --type merge -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":null}}}'
kubectl get storageclass

If the saved file had "false", set that value back:

kubectl patch storageclass fast -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"false"}}}'
kubectl get storageclass

The Kubernetes pages do not say that the undo changes claims that were already updated to fast; check them with kubectl get pvc. The listing should no longer show (default) against fast.

Give the claim a class, or a matching volume

A claim that must use a particular class names it in spec.storageClassName; the volumes page shows storageClassName: slow in a claim. A claim that carries an explicit empty storageClassName binds only to volumes that also have an empty class. Kubernetes documentation gives no procedure for changing an existing claim from one class to another, and removing a claim is a deletion that can lose data once a volume is bound. For a claim that holds no data, a new claim that names the class is the plain route. Check what uses the old claim before anyone removes it.

For a static volume, make capacity, access mode, class and any selector labels match the claim. The volumes page says the ReadWriteOnce mode allows one node to mount the volume read-write.

Provisioner problems

Where the event names an external provisioner, the fix is in that provisioner's own pods and registration. That provisioner's own vendor documentation covers it; the Kubernetes message itself says only to verify that it is running and correctly registered.

Example (illustrative): in namespace shop, claim data-db01 requests 100Gi and has no storageClassName. kubectl get storageclass lists fast and slow, and neither is marked (default). kubectl get pv shows one Available volume of 50Gi with no class, which cannot satisfy 100Gi. The event reads no persistent volumes available for this claim and no storage class is set. The engineer saves the fast class, patches it as the default, and the claim is updated to fast and provisioned.

Confirm the fix

  1. kubectl get pvc -n shop shows the claim Bound and names its volume.
  2. kubectl describe pvc <claim-name> -n shop shows the class now set, with no new FailedBinding event.
  3. kubectl get pv shows the volume Bound to that claim.
  4. The pod that uses the claim leaves Pending and starts.

What to watch afterwards

  • Exactly one StorageClass marked default. The StorageClass page says to try to keep it to one.
  • Claims that set storageClassName: "" on purpose, because a later default class does not change them.
  • Volumes left in Released, which hold old data until someone reclaims them.
  • The provisioner's pods after cluster upgrades.

Risks and limits

  • These commands have not been run or lab-tested.
  • The event texts come from Kubernetes source code at release tag v1.34.0. Wording can differ in other releases, so match on meaning if your text differs.
  • The change-default page says that deleting the default StorageClass may not work, because the add-on manager running in the cluster may re-create it.
  • A default class that provisions real storage creates real volumes and can create cost. Choose the class with that in mind.

Sources