Fix: Kubernetes MountVolume.SetUp Failed (ConfigMap Not Found)

The Error

You’ve just pushed a new deployment, but the Pod is stuck. It has been sitting in the ContainerCreating state for five minutes, and your application logs are completely empty. When you dig deeper using kubectl describe pod, you’ll likely see a series of Warning events at the bottom of the output:

Events:
  Type     Reason       Age                From               Message
  ----     ------       ----               ----               -------
  Warning  FailedMount  12s (x5 over 44s)  kubelet            MountVolume.SetUp failed for volume "config-vol" : configmap "app-config" not found

Basically, the Kubelet on your worker node is trying to mount a ConfigMap or Secret into the container's filesystem, but the resource is missing. Kubernetes won't let the container start without its required dependencies. It will simply keep retrying in the background, hoping the resource appears.

Root Causes

Usually, you are looking at one of three common culprits:

• Namespace Mismatch: You created the ConfigMap in default, but your Pod is running in production.
• YAML Typos: A simple case-sensitivity error or a misspelled name in your Deployment manifest.
• Missing Resource: The ConfigMap was never created, or perhaps a teammate deleted it to clean up the cluster.

Step-by-Step Troubleshooting

1. Verify the Resource and Namespace

Kubernetes resources like ConfigMaps and Secrets are namespaced. They cannot be mounted across boundaries. If your Pod lives in the web-stack namespace, your ConfigMap must be there too. Run this command to check:

# Replace 'web-stack' with your actual namespace
kubectl get configmap app-config -n web-stack

If you see Error from server (NotFound), you've found the gap. You need to recreate the resource in the correct location.

2. Check for Case-Sensitivity and Typos

Kubernetes is picky about naming. App-Config is not the same as app-config. Open your deployment manifest and compare the volumes section against the actual name in the cluster.

# Check your deployment manifest
spec:
  volumes:
    - name: config-vol
      configMap:
        name: app-config # <-- This must match 'kubectl get configmap' exactly

3. Create the Missing ConfigMap

If the resource is truly missing, you can create it on the fly to unblock your deployment. For example, if your app expects a config.yaml file, run:

kubectl create configmap app-config --from-literal=API_URL="https://api.example.com" -n web-stack

Once created, you don't need to restart the Pod. The Kubelet usually retries the mount every 10 to 20 seconds. As soon as it finds the ConfigMap, the Pod will transition to Running automatically.

4. Using Optional Mounts

Sometimes a configuration file isn't strictly necessary for the app to boot. In these cases, you can mark the volume as optional. This prevents the entire Pod from hanging if the ConfigMap is deleted.

      volumes:
        - name: config-vol
          configMap:
            name: app-config
            optional: true # <-- The Pod will start even if the ConfigMap is missing

What about Secrets?

The logic is identical for Secrets. If you see an error referencing secret "db-password" not found, use the same troubleshooting steps but swap the commands to target secrets:

kubectl get secret db-password -n web-stack

Verification

To confirm everything is back on track, watch the Pod status. You are looking for the Started container message in the events log.

kubectl get pods -n web-stack
# Status should now be 'Running'

kubectl describe pod <pod-name> -n web-stack
# Look for: "Successfully mounted volumes for pod..."

Prevention Tips

Manual fixes work in a pinch, but automation prevents these headaches from reaching production. Bundle your ConfigMaps and Deployments in the same Helm chart or Kustomize folder. This ensures they are always applied as a single unit. Additionally, using a GitOps tool like ArgoCD will highlight missing dependencies in a visual dashboard before you even check the CLI.