🚨 Helm Error Guide: 'chart requires kubeVersion' — Fix Incompatible Install Failures

Overview

helm install or helm upgrade fails immediately with chart requires kubeVersion: ... which is incompatible with Kubernetes. The chart’s Chart.yaml declares a kubeVersion constraint — a semver range of Kubernetes versions it supports — and Helm compares it against your cluster’s reported version. If your cluster falls outside the range, Helm refuses to render or install the chart at all. This is a pre-flight guard: the chart author is telling you it uses APIs or features that only exist in certain Kubernetes versions.

The literal error looks like this:

Error: INSTALLATION FAILED: chart requires kubeVersion: >=1.28.0-0 which is incompatible with
Kubernetes v1.26.5

It fires before any resource is created, so nothing is applied. The right fix depends on why the mismatch exists: your cluster may genuinely be too old (upgrade it), the chart may be over-strict, or Helm may be misreading the version (for example against a version with a vendor suffix like v1.27.6-eks-1234). Force-overriding is possible but risks installing a chart whose manifests your cluster cannot actually serve.

Symptoms

• helm install/upgrade/template fails with chart requires kubeVersion: <range> which is incompatible with Kubernetes <version>.
• The failure is instant; no Kubernetes objects are created.
• helm template --kube-version behaves differently from a live install (offline default vs live discovery).
• The cluster version reported by kubectl version sits outside the chart’s declared range.

helm install monitoring prometheus-community/kube-prometheus-stack

Error: INSTALLATION FAILED: chart requires kubeVersion: >=1.28.0-0 which is incompatible with
Kubernetes v1.26.5

Common Root Causes

1. Cluster genuinely older than the chart supports

The most straightforward cause: the chart needs newer Kubernetes APIs/features and your cluster predates them. The chart is correctly refusing to install.

kubectl version -o json | grep -i gitVersion

"gitVersion": "v1.26.5"

If the chart requires >=1.28.0-0, a 1.26 cluster is too old — upgrade the cluster or use a chart version that supports 1.26.

2. Vendor version suffix confusing the comparison

Managed clusters report versions like v1.27.6-eks-1234 or v1.28.3-gke.100. A kubeVersion constraint without a -0 pre-release floor can fail to match a version carrying a build suffix, producing a false incompatibility.

kubectl version -o json | grep gitVersion

"gitVersion": "v1.28.3-eks-abc1234"

A properly written constraint uses >=1.28.0-0 so pre-release/suffix versions are included; if the chart’s constraint omits the -0, the suffix can trip it.

3. Over-strict constraint in the chart

The chart author pinned a tighter range than the chart actually needs (e.g. >=1.28.0 <1.29.0), so a 1.29 cluster is wrongly rejected.

4. helm template default vs the live cluster

helm template uses a built-in default Kubernetes version (not your cluster) unless you pass --kube-version, so results can differ from a live install and mislead diagnosis.

5. An umbrella chart’s subchart carries the constraint

The constraint may live in a dependency, not the top-level chart, so the failing kubeVersion is not the one you inspected.

Diagnostic Workflow

Step 1: Read the required range and your version

helm install <rel> <chart>
kubectl version -o json | grep gitVersion

Compare the kubeVersion range in the error against your cluster’s gitVersion.

Step 2: Inspect the chart’s declared constraint

helm show chart <chart> | grep -i kubeVersion

kubeVersion: '>=1.28.0-0'

Step 3: Decide upgrade vs chart version vs override

If the cluster is truly too old, plan a cluster upgrade or pick an older chart version that supports your Kubernetes:

helm search repo <chart> --versions | head

Step 4: For a false-positive suffix, verify the real capability

Confirm your cluster actually serves the APIs the chart needs (via kubectl api-resources/api-versions) before considering an override.

Step 5: Override only when you are certain

--kube-version (with helm template) or the appropriate flag can bypass the check for rendering, but only do so when you have verified compatibility.

helm template <rel> <chart> --kube-version 1.28.3

Example Root Cause Analysis

A platform team installs a monitoring stack on an EKS cluster and it fails:

helm install monitoring prometheus-community/kube-prometheus-stack -n monitoring

Error: INSTALLATION FAILED: chart requires kubeVersion: >=1.28.0-0 which is incompatible with
Kubernetes v1.27.6-eks-a1b2c3

Checking the cluster version:

kubectl version -o json | grep gitVersion

"gitVersion": "v1.27.6-eks-a1b2c3"

The cluster is genuinely 1.27, and the chart requires >=1.28.0-0 because it ships CRDs/APIs that need 1.28. This is not a suffix false-positive — 1.27 is below the floor. The correct fix is to use a chart version that still supports 1.27:

helm search repo prometheus-community/kube-prometheus-stack --versions | head

NAME                                            CHART VERSION   APP VERSION
prometheus-community/kube-prometheus-stack      61.9.0          ...
prometheus-community/kube-prometheus-stack      58.2.2          ...

Pinning an earlier chart version whose kubeVersion allows 1.27 installs cleanly:

helm install monitoring prometheus-community/kube-prometheus-stack \
  --version 58.2.2 -n monitoring

The team schedules the cluster upgrade to 1.28+ so it can move back to the latest chart.

Prevention Best Practices

• Track your cluster’s Kubernetes version against the kubeVersion of the charts you depend on, and upgrade clusters before charts outgrow them.
• Pin chart versions in CI/GitOps so a helm repo update cannot pull a chart that suddenly requires a newer Kubernetes.
• When authoring charts, write kubeVersion constraints with a -0 pre-release floor (>=1.28.0-0) so managed-cluster version suffixes match correctly.
• Use helm show chart to read a chart’s kubeVersion before adopting it, and check subchart constraints in umbrella charts.
• Verify actual API availability with kubectl api-resources before ever overriding the check. See more in Kubernetes & Helm guides.

Quick Command Reference

# See the required range and the failure
helm install <rel> <chart>

# Your cluster's version
kubectl version -o json | grep gitVersion

# The chart's declared constraint
helm show chart <chart> | grep -i kubeVersion

# Find a chart version that supports your cluster
helm search repo <chart> --versions | head

# Render against a specific version (verify compatibility first)
helm template <rel> <chart> --kube-version 1.28.3

Conclusion

chart requires kubeVersion: ... which is incompatible with Kubernetes means the chart’s declared Kubernetes range does not include your cluster’s version, so Helm refuses to install. The usual causes:

1. The cluster is genuinely older than the chart supports.
2. A managed-cluster version suffix trips an under-specified constraint.
3. The chart’s constraint is stricter than necessary.
4. helm template uses a default version, not your cluster’s.
5. A subchart in an umbrella chart carries the constraint.

Compare the range to kubectl version, then upgrade the cluster or pin a compatible chart version — and override only after verifying the required APIs exist. For ad-hoc triage, the free incident assistant can turn a kubeVersion failure into the right chart-version or upgrade decision.