Volume mount failed — pod cannot start
Production Risk
Pod cannot start; stateful workloads are completely unavailable.
FailedMount is a kubelet event indicating it could not mount one or more volumes before the container could start. The pod is stuck in ContainerCreating or Pending state. Common causes include missing PVCs, NFS mount failures, secret/configmap references that do not exist, and CSI driver errors.
- 1PersistentVolumeClaim referenced in the pod spec does not exist or is not bound
- 2NFS or network filesystem is unreachable from the node
- 3CSI driver pod is not running or has an error
- 4Secret or ConfigMap referenced as a volume does not exist
Pod is stuck in ContainerCreating for an extended period; describe shows FailedMount events.
kubectl describe pod mypod | grep -A 20 "Events:" # Warning FailedMount kubelet Unable to attach or mount volumes: # unmounted volumes=[my-pvc], unattached volumes=[my-pvc]: # timed out waiting for the condition
expected output
Warning FailedMount ... Unable to attach or mount volumes: unmounted volumes=[my-pvc]
Fix 1
Check PVC status
WHEN Pod references a PVC
kubectl get pvc -n mynamespace # Ensure PVC is Bound, not Pending kubectl describe pvc my-pvc
Why this works
A Pending PVC means storage has not been provisioned; a Bound PVC should be mountable.
Fix 2
Verify CSI driver is running
WHEN Using CSI-backed storage
kubectl get pods -n kube-system | grep csi kubectl describe pod <csi-pod-name> -n kube-system
Why this works
CSI driver DaemonSet pods must be Running on every node that needs to mount the volume.
Fix 3
Verify Secret/ConfigMap volumes exist
WHEN Volume references a Secret or ConfigMap
kubectl get secret my-secret -n mynamespace kubectl get configmap my-config -n mynamespace
Why this works
Secrets and ConfigMaps used as volumes must exist in the same namespace as the pod.
Kubernetes Documentation
Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev