🚨 Flux Error: Kustomization Dependency Not Ready Stalls GitOps Reconciliation

Overview

Flux lets one Kustomization declare dependsOn another so resources apply in order. If the upstream Kustomization is not healthy, the dependent one refuses to reconcile and reports:

Status:
  Conditions:
    Type:     Ready
    Status:   False
    Reason:   DependencyNotReady
    Message:  dependency 'flux-system/infrastructure' is not ready

Or with flux get:

NAME          READY   MESSAGE
infrastructure  False  Applied revision main@sha1:... but health check failed
apps            False  dependency 'flux-system/infrastructure' is not ready

The downstream Kustomization (usually your applications) never applies until the dependency becomes Ready, so a rollout stalls with no obvious error on the app itself.

Symptoms

• A Kustomization is Ready: False with Reason: DependencyNotReady.
• The dependent Kustomization never applies its manifests; changes to it appear ignored.
• An upstream Kustomization named in dependsOn is itself Ready: False.
• flux get kustomizations shows a chain where the failure is upstream, not in the app.
• Reconciliation retries on the interval but never progresses.

Common Root Causes

• Upstream reconciliation failed — the dependency’s own apply errored (bad manifest, missing CRD, invalid values).
• Upstream health check failing — healthChecks on the dependency reference a resource that never becomes healthy (a Deployment stuck Progressing).
• Wrong dependency reference — dependsOn names a Kustomization in the wrong namespace or a name that does not exist.
• CRD-before-CR ordering — the dependent applies custom resources whose CRDs are provided by an upstream that has not finished.
• Circular dependency — two Kustomizations depend on each other and neither can become ready.
• Timeout too short — the dependency’s timeout expires before a slow-starting workload is healthy.

Diagnostic Workflow

List all Kustomizations to find where the chain breaks:

flux get kustomizations --all-namespaces

Inspect the dependent Kustomization’s condition and which dependency it is waiting on:

kubectl -n flux-system get kustomization apps -o jsonpath='{.status.conditions}' | jq
kubectl -n flux-system get kustomization apps -o jsonpath='{.spec.dependsOn}' | jq

Now inspect the UPSTREAM dependency — that is where the real failure is:

flux get kustomization infrastructure
kubectl -n flux-system describe kustomization infrastructure

If the upstream uses health checks, find the unhealthy resource:

kubectl -n flux-system get kustomization infrastructure \
  -o jsonpath='{.spec.healthChecks}' | jq
kubectl -n <target-ns> get deploy,sts,ds --field-selector 'status.readyReplicas!=1' 2>/dev/null

Force a reconcile once the root cause is fixed:

flux reconcile kustomization infrastructure --with-source

Example Root Cause Analysis

After a Git push, the apps Kustomization stopped applying. flux get kustomizations showed apps as DependencyNotReady waiting on infrastructure, and infrastructure itself as Ready: False with health check failed. The mistake was upstream, not in the apps.

describe kustomization infrastructure pointed at a health check on a cert-manager Deployment. kubectl get deploy in that namespace showed it stuck at 0/1 ready:

cert-manager-webhook   0/1   ImagePullBackOff

A typo in the image tag from the same commit left the webhook pod unable to pull, so the Deployment never became healthy, so infrastructure’s health check never passed, so apps — correctly — refused to deploy on top of an unhealthy platform. Flux’s dependency gate was doing its job: it prevented applications from rolling onto a broken foundation.

Fixing the image tag in Git and running flux reconcile kustomization infrastructure --with-source let the webhook pull, the Deployment reach 1/1, infrastructure go Ready: True, and apps reconcile automatically on the next pass.

Prevention Best Practices

• Always debug the UPSTREAM dependency first — DependencyNotReady means the problem is in what you depend on, not the dependent.
• Keep dependsOn references correct (right name and namespace) and avoid circular dependencies between Kustomizations.
• Scope healthChecks to the resources that truly gate readiness, so a dependency is only “ready” when the platform actually works.
• Set timeout values long enough for slow-starting workloads but short enough to surface genuine failures.
• Order CRDs before the custom resources that use them via dependsOn so applies do not fail on missing kinds.
• Alert on any Kustomization Ready: False for longer than a few reconcile intervals so a stalled chain is caught early.

Quick Command Reference

# Find where the chain breaks
flux get kustomizations --all-namespaces

# What is the dependent waiting on?
kubectl -n flux-system get kustomization apps -o jsonpath='{.spec.dependsOn}' | jq

# Root-cause the UPSTREAM dependency
flux get kustomization infrastructure
kubectl -n flux-system describe kustomization infrastructure

# Find the unhealthy gating resource
kubectl -n <ns> get deploy,sts --field-selector 'status.readyReplicas!=1'

# Reconcile after fixing
flux reconcile kustomization infrastructure --with-source

Conclusion

DependencyNotReady is not a Flux failure — it is Flux refusing to deploy your apps onto an unhealthy foundation, exactly as dependsOn instructs. The mistake is staring at the stalled dependent Kustomization when the real error is one level up. Walk the chain with flux get kustomizations, fix the upstream reconciliation or its failing health check, and the dependent reconciles on its own. Keep health checks meaningful and dependencies acyclic so the ordering protects you instead of trapping you.