Kubernetes FailedMount: unable to attach or mount volumes

Diagnose Kubernetes FailedMount by reading pod events, checking configmap and secret existence, and resolving node-level volume conflicts.

intermediatedebuggingkubernetesstoragevolumes

Symptoms

Warning FailedMount: MountVolume.SetUp failed for volume
The pod stays in ContainerCreating
Events mention a configmap, secret, or volume not found

Possible causes

A referenced ConfigMap or Secret does not exist in the namespace
A PVC is not bound or the StorageClass cannot provision
A volume is already attached to another node (RWO conflict)
A hostPath or CSI driver is unavailable on the scheduled node

Diagnosis steps

Read the pod events for the failed volume name

kubectl describe pod <pod>

Interpretation

Events name the volume and the specific reason, such as configmap not found.

Verify the referenced objects exist

kubectl get configmap,secret -n <ns>

Interpretation

A missing object in the namespace is the most common cause.

Check PVC binding and node attachment

kubectl get pvc -n <ns>

Interpretation

Pending PVCs or RWO volumes attached elsewhere explain mount failures.

Root cause

FailedMount means the kubelet could not prepare a volume for the pod. The volume definition is valid enough to schedule, but the backing object is missing, unbound, already in use on another node, or unsupported by the node, so the container never starts and the pod stays in ContainerCreating.

Fix

Create the missing ConfigMap or Secret in the correct namespace and reference it exactly. Ensure the PVC binds by checking StorageClass and capacity, and for RWO volumes confirm the pod is not scheduled away from the attaching node. Fix hostPath paths and CSI driver availability per node.

Verify the fix

Describe the pod again; the FailedMount event is gone, the pod transitions to Running, and kubectl get pvc shows the volume Bound.

Symptoms

A pod is stuck in ContainerCreating with Warning FailedMount events. The container image may be fine; the failure is in preparing its volumes.

Diagnosis

Read events and verify the referenced objects:

kubectl describe pod myapp-abc -n prod
kubectl get configmap,secret,pvc -n prod

Events name the volume and often the exact reason.

Fix

Create missing objects and align references:

kubectl create configmap app-config --from-file=config.yaml -n prod

volumes:
  - name: cfg
    configMap:
      name: app-config   # must exist in the same namespace

Verification

Re-describe the pod; the FailedMount event is absent, the pod reaches Running, and any PVC shows Bound, confirming every volume mounted successfully.

Read-Write-Once Attachment Conflicts

A common FailedMount that looks like a missing object is actually an attachment conflict. A PersistentVolume with ReadWriteOnce access can attach to only one node at a time, so when a Deployment is scaled or a pod is rescheduled, the new pod on a different node waits while the volume stays attached to the old one. Events mention a multi-attach error rather than a missing resource, and the fix is to wait for the old attachment to release, confirm the old pod terminated, or use a storage class with a topology that supports the access mode the workload needs.