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.
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.
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.yamlIn overlays/dev/kustomization.yaml, the base reference must point correctly:
bases:
- ../../baseUse relative paths starting from the overlay directory. Test with:
kustomize build overlays/devIf 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 versionUse the standalone binary for overlay builds:
kustomize build overlays/dev
# NOT:
kubectl kustomize overlays/dev # Uses bundled, potentially outdated versionThis 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 -vCheck 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/devFix 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 resourcesFor 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: 2Common 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.yamlOr 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/devHowever, the better solution is restructuring to avoid cross-directory references. Instead of:
# overlays/dev/kustomization.yaml (WRONG - references ../shared)
resources:
- ../../shared/config.yamlUse components or include shared resources in the base:
# overlays/dev/kustomization.yaml (CORRECT)
bases:
- ../../base # base includes shared filesAvoid 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.
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.
No subnets found for EKS cluster
How to fix "eks subnet not found" in Kubernetes
unable to compute replica count
How to fix "unable to compute replica count" in Kubernetes HPA
error: context not found
How to fix "error: context not found" in Kubernetes
default backend - 404
How to fix "default backend - 404" in Kubernetes Ingress
serviceaccount cannot list resource
How to fix "serviceaccount cannot list resource" in Kubernetes