flux HelmRelease reconciliation failed: how to read the error

Not specified by the original author.

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.

Not specified by the original author.

TL;DR

Also follow the version upgrade procedure: before upgrading to v2.7, run flux migrate. See the v2.7.0 upgrade notes at fluxcd.io for the full procedure.

Steps

1. Reported in Flux CD: Flux reconcilation failed after upgrade with "flux install" command.
2. If Flux reconciliation fails after running 'flux install' to upgrade, it is because you bootstrapped Flux in Git and then overwrote the controllers with install. To upgrade a Git-bootstrapped Flux, rerun bootstrap, not install: flux bootstrap github (or your provider) with the same flags. Also follow the version upgrade procedure: before upgrading to v2.7, run flux migrate. See the v2.7.0 upgrade notes at fluxcd.io for the full procedure.

When to use

Use this skill when you run into "Flux reconcilation failed after upgrade with "flux install" command".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

Versions mentioned in the source: v2.7, v2.7.0. If you are on something much newer or older, the details may have shifted.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Edge cases

• Also follow the version upgrade procedure: before upgrading to v2.7, run flux migrate.

In gh:fluxcd/flux2#3622 (https://github.com/fluxcd/flux2/issues/3622), the reporter ran into this: Reported in Flux CD: Flux reconcilation failed after upgrade with "flux install" command. The verified resolution: If Flux reconciliation fails after running 'flux install' to upgrade, it is because you bootstrapped Flux in Git and then overwrote the controllers with install. To upgrade a Git-bootstrapped Flux, rerun bootstrap, not install: flux bootstrap github (or your provider) with the same flags. Also follow the version upgrade procedure: before upgrading to v2.7, run flux migrate. See the v2.7.0 upgrade notes at fluxcd.io for the full procedure.

Not specified by the original author.

TL;DR

Flux CD - ### Describe the bug Hi all, I am trying to install spark from oci: https://artifacthub.io/packages/helm/bitnami/spark ``` apiVersion: v1 kind: Namespace metadata name: spark --- apiVersion: source.toolkit.fluxcd.io/v1beta2 kind: OCIRepository metadata name: bitnami-spark namespace: flux-system spec: interval: 10m url: oci://registry-1.docker.io/bitnamicharts/spark --- apiVersion: helm.toolkit.fluxcd.

Steps

1. First check your apiVersion: use HelmRelease v2, not v2beta1, which still requires spec.chart. If the error persists on v2, the reviewed case turned out to be stale CRDs from the Azure Flux extension and the error disappeared on a fresh cluster, so check for a stale or conflicting extension install.

When to use

Use this skill when you run into "HelmRelease.helm.toolkit.fluxcd.io is invalid: spec.chart: Required value - when using spec.chartref".

When not to use

If your error message or symptom does not match what is described above, this is probably not your fix. Search for your exact error text instead of forcing this one to fit.

Versions

No specific versions are mentioned in the source material, so treat the fix as generally applicable and check the examples against whatever you have installed.

Why this happens

The original report does not dig into a root cause. It documents the symptom and the fix that resolved it.

Sources

• https://artifacthub.io/packages/helm/bitnami/spark
• https://github.com/fluxcd/flux2/issues/5116

In gh:fluxcd/flux2#5116 (https://github.com/fluxcd/flux2/issues/5116), the issue reported: ### Describe the bug Hi all, I am trying to install spark from oci: https://artifacthub.io/packages/helm/bitnami/spark ``` apiVersion: v1 kind: Namespace metadata name: spark --- apiVersion: source.toolkit.fluxcd.io/v1beta2 kind: OCIRepository metadata name: bitnami-spark namespace: flux-system spec: interval: 10m url: oci://registry-1.docker.io/bitnamicharts/spark --- apiVersion: helm.toolkit.fluxcd. The verified answer: First check your apiVersion: use HelmRelease v2, not v2beta1, which still requires spec.chart. If the error persists on v2, the reviewed case turned out to be stale CRDs from the Azure Flux extension and the error disappeared on a fresh cluster, so check for a stale or conflicting extension install.