How to fix Kustomize overlay error in Kubernetes

KubernetesINTERMEDIATEMEDIUMUpdated Dec 6, 2025· 128 views

Kustomize overlay errors occur when base directory references are incorrect, circular dependencies exist, or overlay structure is malformed. Fix by verifying base paths in kustomization.yaml, ensuring correct directory structure, and using kustomize build to preview changes before applying.

Quick fix

Fixes Kustomize overlay error

my-app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml
  1. Verify directory structure and base references
  2. Install standalone kustomize binary instead of kubectl kustomize
  3. Detect and fix circular dependency cycles
  4. Fix patch references and resource selection in overlays
kubernetes — error
my-app/
├── base/
│   ├── kustomization.yaml
│   ├── deployment.yaml
│   └── service.yaml
└── overlays/
    ├── dev/
    │   └── kustomization.yaml
    ├── staging/
    │   └── kustomization.yaml
    └── prod/
        └── kustomization.yaml
Kustomize overlay error

What this error means

Kustomize overlays are directories containing kustomization.yaml files that customize base Kubernetes configurations for different environments (dev, staging, prod). Overlay errors happen when Kustomize cannot resolve dependencies between overlays and bases, typically due to missing base references, incorrect relative paths, circular dependency cycles, or malformed YAML structure. These errors prevent kustomize build from generating the final Kubernetes manifests, blocking deployments. Understanding overlay structure and proper referencing is critical for multi-environment Kubernetes configurations.

Typical symptoms

  • Error message "cycle detected: candidate root contains visited root" when building overlays
  • Kustomize build fails with "security; file is not in or below the overlay directory" warning
  • Cannot reference shared resources across multiple overlays without LoadRestrictionsNone flag
  • Overlay patches don't apply because they cannot find or identify the target resource
  • ConfigMap or Secret replacements in overlays silently fail or apply incorrectly
  • Helm chart value overrides in overlays don't work; base values persist instead

Common causes

  1. Base path in overlay kustomization.yaml points to non-existent directory or uses wrong relative path
  2. Circular references: overlay references base that includes overlay, creating dependency cycle
  3. Missing or malformed kustomization.yaml in base or overlay directory
  4. Load restrictor security prevents overlays from referencing files outside overlay boundaries without explicit flag
  5. Overlay patches reference non-existent resources (typos in kind, name, namespace)
  6. Using kubectl kustomize instead of kustomize binary, limiting supported features (transformers, components)
  7. Incorrect ordering of bases and resources in kustomization.yaml causing merge conflicts

How to fix "Kustomize overlay error"

1Verify directory structure and base references

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

bash
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:

yaml
bases:
  - ../../base

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

bash
kustomize build overlays/dev

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

2Install standalone kustomize binary instead of kubectl kustomize

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

bash
# 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:

bash
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.

3Detect and fix circular dependency cycles

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

bash
kustomize build overlays/dev -v

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

yaml
# 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:

yaml
# 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.

4Fix patch references and resource selection in overlays

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

yaml
# 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:

bash
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.

5Use kustomize build preview before kubectl apply

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

bash
# 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):

bash
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.

6Handle load restrictor errors for cross-directory references

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:

bash
# 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:

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

Use components or include shared resources in the base:

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

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

7For Helm chart overlays, use patchesJson6902 instead of helm values patching

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

yaml
# 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:

bash
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.

Advanced notes

For sharing resources and patches across multiple overlays without duplicating code, use Kustomize components (kustomize.config.k8s.io/v1alpha1), which encapsulate both resources and patches in a reusable unit. When dealing with ConfigMap or Secret replacements via overlays, ensure the overlay configMapGenerator uses behavior: replace, and remember that the replacement happens at overlay build time, not merge time. commonLabels defined in the base are only applied to resources Kustomize knows about at that stage; resources added in the overlay won't receive base labels unless explicitly patched. For numeric keys in ConfigMaps (a known Kustomize bug), use string keys with quotes: "123" instead of 123. When using multiple overlays in a GitOps pipeline (ArgoCD, Flux), understand that ArgoCD supports Kustomize overlays natively via kustomize argument in the app spec. SELinux and AppArmor can interfere with kustomize build on restricted systems; disable or configure permissive mode for development. Performance tip: Build large overlay structures in CI/CD to catch errors early; don't wait until kubectl apply to discover Kustomize errors.

Frequently asked questions

What does "Kustomize overlay error" mean?
yaml files that customize base Kubernetes configurations for different environments (dev, staging, prod). Overlay errors happen when Kustomize cannot resolve dependencies between overlays and bases, typically due to missing base references, incorrect relative paths, circular dependency cycles, or malformed YAML structure. These errors prevent kustomize build from generating the final Kubernetes manifests, blocking deployments.
How do I fix "Kustomize overlay error"?
Kustomize overlay errors occur when base directory references are incorrect, circular dependencies exist, or overlay structure is malformed. Fix by verifying base paths in kustomization.yaml, ensuring correct directory structure, and using kustomize build to preview changes before applying.
What causes "Kustomize overlay error"?
Base path in overlay kustomization.yaml points to non-existent directory or uses wrong relative path Circular references: overlay references base that includes overlay, creating dependency cycle Missing or malformed kustomization.yaml in base or overlay directory
Is the "Kustomize overlay error" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading