Kubernetes ConfigMap Not Found Fix

In this tutorial, you'll learn about Kubernetes ConfigMap Not Found Fix. We cover key concepts, practical examples, and best practices.

The Problem

Your pod fails to start with a ConfigMap-related error:

Events:
  Type     Reason       Age   From               Message
  ----     ------       ----  ----               -------
  Warning  FailedMount  10s   kubelet            ConfigMap "my-config" not found

Or the pod is created but environment variables are empty:

kubectl exec my-pod -- env | grep APP_

The pod references a ConfigMap that does not exist, is in the wrong namespace, or has a typo in the name.

Quick Fix

Step 1: Verify the ConfigMap exists

kubectl get configmap my-config

Error from server (NotFound): configmaps "my-config" not found

If the ConfigMap does not exist, create it:

kubectl create configmap my-config --from-literal=APP_ENV=production --from-literal=APP_DEBUG=false

Or from a file:

kubectl create configmap my-config --from-file=app.properties

Step 2: Check the namespace

ConfigMaps are namespaced. A pod in namespace staging cannot see a ConfigMap in production:

kubectl get configmap --all-namespaces | grep my-config

WRONG -- pod and ConfigMap in different namespaces:

apiVersion: v1
kind: Pod
metadata:
  namespace: staging       # pod in staging namespace
spec:
  containers:
  - envFrom:
    - configMapRef:
        name: my-config   # ConfigMap exists in "production" namespace

RIGHT -- ensure both are in the same namespace, or use namespace-qualified ConfigMap references (not supported -- always keep them co-located).

Step 3: Check the ConfigMap key names

kubectl get configmap my-config -o yaml

data:
  app.env: production
  debug: "false"

WRONG -- referencing a key that does not exist:

env:
- name: APP_ENV
  valueFrom:
    configMapKeyRef:
      name: my-config
      key: APP_ENV   # key is "app.env", not "APP_ENV"

RIGHT -- use the exact key name:

env:
- name: APP_ENV
  valueFrom:
    configMapKeyRef:
      name: my-config
      key: app.env

Step 4: Check volume mount path

If the ConfigMap is mounted as a volume:

volumeMounts:
- name: config-volume
  mountPath: /etc/config
volumes:
- name: config-volume
  configMap:
    name: my-config

kubectl exec my-pod -- ls /etc/config

WRONG -- mount path is a file that already exists:

/etc/config is a directory containing key-value pairs, not a single file.

RIGHT -- use subPath to mount a single key as a file:

volumeMounts:
- name: config-volume
  mountPath: /etc/app.properties
  subPath: app.properties

Step 5: Check for updated ConfigMap propagation

When you update a ConfigMap, pods may not see the changes immediately:

# Force pod recreation
kubectl rollout restart deployment my-deployment

For environment variables, the pod must be restarted to pick up new values. For volume mounts, the update propagates within the sync period (usually 60 seconds).

Step 6: Verify ConfigMap data format

Invalid YAML in ConfigMap data prevents mounting:

kubectl describe configmap my-config

If the data values contain binary content or invalid characters, use --from-file instead of --from-literal.

Use DodaTech's Config Inspector to compare ConfigMap contents across namespaces and validate key references before deploying.

Prevention

• Create ConfigMaps before the deployments that reference them.
• Use the same namespace for ConfigMaps and their consuming pods.
• Use kubectl create configmap --dry-run=client -o yaml to validate before applying.
• Add ConfigMap validation to your CI/CD pipeline.
• Use Helm or Kustomize to standardize ConfigMap naming.

Common Mistakes with configmap not found

1. Placing the wildcard pattern first in case expressions, making all subsequent patterns unreachable
2. Using head and tail instead of pattern matching, causing runtime errors on empty lists
3. Forgetting that lazy evaluation defers computation until the value is forced, causing space leaks with unevaluated thunks

These mistakes appear frequently in real-world K8S code. DodaTech's contributors have identified these patterns through analysis of open-source projects and production systems.

Practice Exercise

Write a pure function that safely divides two integers using Maybe, then test it with edge cases like division by zero and negative numbers.

This exercise reinforces the concepts covered in this guide. Try implementing it before checking online solutions.

FAQ