Check overall system health
flux checkConfirms every Flux controller is installed and running before debugging a specific resource.
Check the specific resource's status
flux get kustomizationsThe READY column shows False for anything failing, with a short reason inline.
kubectl describe kustomization my-app -n flux-systemShows the full condition message — usually the exact error (a git clone failure, a manifest apply error, a missing source).
Check the source first
Most Kustomization/HelmRelease failures trace back to their source not being ready — check that before assuming the Kustomization/HelmRelease itself is broken.
flux get sources gitA GitRepository stuck not-ready usually means an auth failure, a branch/tag that doesn't exist, or the repo being unreachable from the cluster.
Force a reconcile with tracing
flux reconcile kustomization my-app --with-sourceReconciles both the source and the Kustomization together, and surfaces the error immediately rather than waiting for the next poll.
Check controller logs directly
flux logs --follow --kind=Kustomization --name=my-appFilters Flux's aggregate log stream to just the controller and object you're investigating.
Suspended and forgotten
A Kustomization or HelmRelease left suspend: true after a debugging session will silently stop reconciling
with no error at all — check suspend status before assuming a reconcile failure.
prune: true and manual resources
With prune: true, Flux deletes any resource it previously created that's no longer in Git — including one you
manually added to the same Kustomization path outside of Flux's management. Keep manually-managed resources out
of paths Flux prunes.