How to fix FailedMount in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 209 views

The FailedMount error occurs when Kubernetes cannot mount a volume to a pod, often due to missing ConfigMaps/Secrets, NFS permission issues, or volume attachment problems.

Quick fix

Fixes FailedMount

kubectl describe pod <pod-name>
  1. Check pod events for specific error
  2. Verify ConfigMaps and Secrets exist
  3. Check PersistentVolume and PVC status
  4. Fix NFS permission issues
kubernetes — error
kubectl describe pod <pod-name>
FailedMount

What this error means

The FailedMount error indicates that Kubernetes was unable to mount a volume at the specified path inside a container. This happens during pod startup after the volume has been attached to the node but before the container can start. Mount failures can occur for various volume types: ConfigMaps, Secrets, PersistentVolumes, NFS shares, and cloud provider disks. The error prevents the pod from transitioning to Running state, leaving it stuck in ContainerCreating. FailedMount often appears after FailedAttachVolume—the attach step must succeed before mounting can begin. If you see both errors, focus on fixing the attachment issue first.

Typical symptoms

  • Pod stuck in ContainerCreating state
  • kubectl describe pod shows FailedMount warning
  • Volume mount timeout after 2+ minutes
  • Container fails to start despite image being pulled
  • Multiple pods on same node failing to mount same volume

Common causes

  1. Referenced ConfigMap or Secret does not exist
  2. NFS server permission denied or export not configured
  3. PersistentVolume not attached or still detaching from another node
  4. Volume already mounted read-write by another pod
  5. Node disk space exhausted preventing mount operations

How to fix "FailedMount"

1Check pod events for specific error

View the detailed mount failure message:

bash
kubectl describe pod <pod-name>

Look for events like:

bash
Warning  FailedMount  MountVolume.SetUp failed for volume "config"
  : configmap "app-config" not found
2Verify ConfigMaps and Secrets exist

If mounting ConfigMaps or Secrets, ensure they exist in the same namespace:

bash
# List ConfigMaps
kubectl get configmap -n <namespace>

# List Secrets
kubectl get secret -n <namespace>

# Create missing ConfigMap
kubectl create configmap app-config --from-file=config.yaml -n <namespace>
3Check PersistentVolume and PVC status

Verify PV is bound and available:

bash
# Check PVC status (should be Bound)
kubectl get pvc -n <namespace>

# Check PV status
kubectl get pv

# Check VolumeAttachments
kubectl get volumeattachments
4Fix NFS permission issues

For NFS mounts, ensure the server is configured correctly:

bash
# On NFS server, check exports
cat /etc/exports
# Should include: /exports *(rw,sync,no_root_squash,no_subtree_check)

# Apply changes
exportfs -ra

In your pod, you may need to set securityContext:

yaml
securityContext:
  fsGroup: 1000
  runAsUser: 1000
5Check node disk space

Mount operations can fail if the node is out of disk space:

bash
# SSH to node or use debug container
kubectl debug node/<node-name> -it --image=busybox

# Check disk space
df -h

Clean up if needed:

bash
# Prune unused container images
crictl rmi --prune
6Remove stale VolumeAttachments

If a volume is stuck attached to a dead node:

bash
# Find the stuck attachment
kubectl get volumeattachments

# Delete it (after confirming the node is truly down)
kubectl delete volumeattachment <attachment-name>

Advanced notes

FailedMount warnings often self-resolve after retries. Kubernetes retries mounts with exponential backoff, so a brief warning during pod startup may not indicate a persistent problem.

For high-concurrency scenarios (>400 pods mounting PVCs simultaneously), you may hit kubelet limits. Increase the kubelet's volume-related settings:

bash
--volume-plugin-dir=/var/lib/kubelet/volumeplugins
--max-parallel-image-pulls=10

Common mount timeout: 2 minutes. If your storage backend is slow, pods may fail before mount completes. Check CSI driver logs for backend-specific issues:

bash
kubectl logs -n kube-system -l app=csi-driver --tail=100

Static pods (defined in /etc/kubernetes/manifests) cannot use ConfigMaps or Secrets—this is a kubelet limitation. Use hostPath volumes instead for static pods.

Frequently asked questions

What does "FailedMount" mean?
The FailedMount error indicates that Kubernetes was unable to mount a volume at the specified path inside a container. This happens during pod startup after the volume has been attached to the node but before the container can start. Mount failures can occur for various volume types: ConfigMaps, Secrets, PersistentVolumes, NFS shares, and cloud provider disks.
How do I fix "FailedMount"?
The FailedMount error occurs when Kubernetes cannot mount a volume to a pod, often due to missing ConfigMaps/Secrets, NFS permission issues, or volume attachment problems.
What causes "FailedMount"?
Referenced ConfigMap or Secret does not exist NFS server permission denied or export not configured PersistentVolume not attached or still detaching from another node
Is the "FailedMount" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading