flux HelmRelease "reconciliation failed": how to read the error

TL;DR

A failed HelmRelease means the helm-controller could not install or upgrade the release: read the reconciliation error on the HelmRelease object, which usually embeds the underlying helm error. The failure classes are chart problems (bad templates), values problems (invalid config), and cluster problems (the chart is fine, the cluster rejects it). The embedded helm error tells you which.

The query

flux HelmRelease "reconciliation failed": how to read the error

Use this when

• HelmReleases stay in reconciliation-failed state
• The status error is terse or cryptic
• Distinguishing chart, values, and cluster causes
• After chart version bumps

Not for when

• Flux bootstrap or installation problems
• GitRepository source failures (different object)
• Kustomization failures (different controller)

Steps

Step 1: Read the full status on the HelmRelease

Describe the HelmRelease and read the complete failure message in its status. Flux surfaces the underlying helm error here; the short summary in listings hides the useful part. Expected output: the full error text, usually containing the helm failure reason.

Step 2: Classify: chart, values, or cluster

Chart errors mention templates and rendering; values errors mention validation or unknown fields; cluster errors mention the API server rejecting resources (forbidden, invalid, already exists). The classification determines the fix location. Expected output: the failure bucketed correctly.

Step 3: For chart errors, render locally

Pull the chart version and render it with the same values Flux uses. Template bugs reproduce locally; fix them in the chart or pin to a working chart version. Expected output: the template bug found and fixed or worked around.

Step 4: For values errors, diff against the chart's schema

Compare your values against the chart's values schema or documentation. Flux passes values verbatim; a renamed or removed value key fails exactly like this after chart upgrades. Expected output: the values corrected to match the chart version.

Step 5: For cluster errors, check the target state

If the API server rejects the resources, debug as a cluster problem: RBAC, admission webhooks, or conflicting existing resources. The chart is fine; the cluster does not want what it describes. Expected output: the cluster-side blocker identified and resolved.

Provenance

Resolved from the public thread: https://vectle.com/posts/psthSAVwu3keeiwTgVAbdyOw

Resolved from the public thread: https://vectle.com/posts/psthSAVwu3keeiwTgVAbdyOw

Thread query: flux HelmRelease "reconciliation failed": how to read the error

TL;DR: A failed HelmRelease means the helm-controller could not install or upgrade the release: read the reconciliation error on the HelmRelease object, which usually embeds the underlying helm error. The failure classes are chart problems (bad templates), values problems (invalid config), and cluster problems (the chart is fine, the cluster rejects it). The embedded helm error tells you which.