How to fix Kustomize overlay error in Kubernetes

Overlay errors often stem from incorrect paths. Check that your directory structure matches the base references in overlay kustomization.yaml:

my-app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml

In overlays/dev/kustomization.yaml, the base reference must point correctly:

bases:
  - ../../base

Use relative paths starting from the overlay directory. Test with:

kustomize build overlays/dev

If you get "no such file or directory", the path is wrong. Verify each segment of the path exists.

The kustomize binary bundled with kubectl is outdated and lacks support for advanced features like transformers and components. Install the standalone binary:

# On macOS
brew install kustomize

# On Linux
curl -s "https://raw.githubusercontent.com/kubernetes-sigs/kustomize/master/hack/install_kustomize.sh" | bash

# Verify installation
kustomize version

Use the standalone binary for overlay builds:

kustomize build overlays/dev

# NOT:
kubectl kustomize overlays/dev  # Uses bundled, potentially outdated version

This resolves errors related to unsupported transformers or components that work in standalone Kustomize but not in kubectl.

Overlay errors like "cycle detected: candidate root contains visited root" indicate circular references. Debug by building with verbose output and tracing the cycle:

kustomize build overlays/dev -v

Check that your base and overlay structure doesn't create a loop. For example, this is WRONG:

# overlays/dev/kustomization.yaml
bases:
  - ../../base

# base/kustomization.yaml
bases:          # ERROR: base references overlay, creating cycle
  - ../overlays/dev

Fix by ensuring overlays only reference bases, and bases never reference overlays:

# overlays/dev/kustomization.yaml (correct)
bases:
  - ../../base      # OK: overlay -> base

# base/kustomization.yaml (correct)
resources:
  - deployment.yaml # OK: base only has local resources

For complex setups, use components instead of nested bases to avoid cycles.

Overlay patches fail if they cannot identify the target resource. Verify patch selectors match your base resources exactly:

# overlays/dev/kustomization.yaml
patchesStrategicMerge:
  - patch.yaml

# patch.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: my-app      # Must match base deployment name exactly
spec:
  replicas: 2

Common mistakes:
- Patch has different apiVersion than base resource
- name in patch doesn't match base (typos are silent failures)
- namespace in patch doesn't match base

Test patch application by building and inspecting output:

kustomize build overlays/dev | grep -A 10 "name: my-app"

If the deployment name doesn't appear, the patch wasn't applied. Fix the selector and try again.

Always preview generated manifests before deploying to catch configuration errors early:

# Preview what kustomize will generate
kustomize build overlays/dev

# Save to file for inspection
kustomize build overlays/dev > manifests.yaml
cat manifests.yaml

# Then apply if correct
kubectl apply -f manifests.yaml

Or pipe directly (after confirming output is correct):

kustomize build overlays/prod | kubectl apply -f -

Preview catches:
- Missing patches or overlays
- Incorrect replicas, image tags, or environment variables
- Namespace misconfigurations
- Secret/ConfigMap merges that didn't apply

This prevents deploying broken configurations to production.

By default, Kustomize restricts overlays from referencing files outside their directory tree for security. If you legitimately need to reference shared files, use the --load-restrictor flag:

# Error: "security; file is not in or below the overlay directory"
kustomize build overlays/dev

# Solution: disable load restrictor
kustomize build --load-restrictor=LoadRestrictionsNone overlays/dev

However, the better solution is restructuring to avoid cross-directory references. Instead of:

# overlays/dev/kustomization.yaml (WRONG - references ../shared)
resources:
  - ../../shared/config.yaml

Use components or include shared resources in the base:

# overlays/dev/kustomization.yaml (CORRECT)
bases:
  - ../../base      # base includes shared files

Avoid LoadRestrictionsNone in production; it's a security risk. Restructure instead.

Overlays struggle with overriding Helm chart values because you cannot patch helmCharts entries directly. Instead, use patchesJson6902 to modify the generated resources:

# base/kustomization.yaml
helmCharts:
- name: nginx
  repo: https://kubernetes.github.io/ingress-nginx
  version: 4.0.0
  valuesInline:
    replicaCount: 1

# overlays/prod/kustomization.yaml
bases:
  - ../../base

patchesJson6902:
  - target:
      group: apps
      kind: Deployment
      name: nginx-ingress-controller
    patch: |-
      - op: replace
        path: /spec/replicas
        value: 3
      - op: replace
        path: /spec/template/spec/containers/0/resources/requests/memory
        value: "512Mi"

Build and verify:

kustomize build overlays/prod | grep -A 5 "replicas"

PatchesJson6902 works on any resource type and is more reliable than trying to override Helm values in overlays.