PVC Mount Failures in Kubernetes
Resolve PersistentVolumeClaim mount failures including Multi-Attach errors and CSI provisioning issues.
Overview
Overview
When a pod cannot mount its PersistentVolumeClaim (PVC), it stays in ContainerCreating indefinitely. The describe output then shows one of a few characteristic errors, each pointing to a different root cause.
The Multi-Attach error
Multi-Attach error for volume X: volume is already exclusively attached to one node and can't be attached to another.
It happens when a ReadWriteOnce (RWO) volume, mountable by pods on a single node only, is requested on a second node while still attached to the first.
- Node failure, draining or pod disruption — The pod moved before the detach from the old node completed
- Old node unreachable — The control plane cannot confirm the detach
- Ungraceful deletion, immediate SIGKILL — The volume controller had not processed the detach before the new pod was scheduled
Access modes by storage
- EBS — ReadWriteOnce — An EBS volume attaches to one EC2 instance at a time: a hardware and OS constraint, not a Kubernetes limitation
- EFS and other NFS-based storage — ReadWriteMany — Mountable by pods on multiple nodes at once
Other failure modes
- CSI driver unhealthy — Dynamic provisioning needs the storage class's CSI driver; without it the PVC stays Pending with an error in its events — Restore the CSI driver pods
- AZ mismatch — An EBS volume lives in one AZ (say us-east-1a); a pod scheduled in us-east-1b cannot attach it — StatefulSets keep each pod bound to its PVC across restarts, so it returns to the volume's zone; Deployments with PVCs need careful topology constraints
> [!TIP] Most PVC mount failures are fixed by removing the orphaned attachment, using StatefulSets for stateful workloads, or topology spread constraints that keep pods in their volumes' AZ.
Key concepts
- ReadWriteOnce (RWO)
- A PVC access mode allowing the volume to be mounted by pods on a single node at a time — enforced at the storage driver level (EBS) and the Kubernetes volume controller.
- Multi-Attach Error
- A volume mount failure when a Kubernetes controller tries to attach an RWO volume to a second node while the volume is still considered attached to the first.
- CSI Driver
- A Container Storage Interface plugin that implements volume provisioning, attachment, and mounting for a specific storage backend (aws-ebs-csi-driver, efs-csi-driver, etc.).
- StorageClass
- A Kubernetes resource that defines a volume provisioner and parameters — the provisioner is called when a PVC is created, creating and binding the backing storage volume.
- StatefulSet
- A Kubernetes workload type that provides stable pod identity and stable PVC-to-pod binding across restarts, ensuring a pod always returns to the same persistent volume.
When to use it
- Diagnosing pods stuck in ContainerCreating with PVC mount errors
- Explaining and resolving Multi-Attach errors for RWO EBS volumes
- Choosing between RWO and RWX access modes for specific workload patterns
- Debugging CSI driver provisioning failures that leave PVCs in Pending state
- Designing StatefulSet storage configurations for high-availability databases in Kubernetes
Interview questions
- What causes the Multi-Attach error and what is the safe way to resolve it?
- How do you debug a PVC that stays in Pending state without a bound volume?
- How do StatefulSets handle PVC binding differently from Deployments, and why does it matter for stateful workloads?
Sign up free to read the full topic
More Troubleshooting topics
- Multi-Region High Latency
- NAT Gateway Bandwidth and Throttling
- Network Bandwidth Saturation
- OOMKilled Pod Diagnosis
- Packet Loss and Network Degradation
- Pods Stuck Pending
- RDS CPU at 100%
- RDS Read Replica Replication Lag
- S3 High Latency Spikes
- Slow Query Diagnosis
- Staging Passes, Prod Fails
- TLS Certificate Expiry Incidents
Start free on Cariara · Coding problems · System design studio