Helm "chart requires kubeVersion: ... which is incompatible" in CI

By Kaveh Alemi·Latchkey

A chart declares a kubeVersion range in Chart.yaml, and the target cluster’s Kubernetes version falls outside it. Helm refuses to install rather than render manifests the cluster may not support.

What this error means

helm install/upgrade/template fails with Error: chart requires kubeVersion: >=1.27.0-0 which is incompatible with Kubernetes v1.25.x. It is deterministic - the cluster version genuinely does not meet the chart’s constraint.

Error: chart requires kubeVersion: >=1.27.0-0 which is incompatible with
Kubernetes v1.25.9

Common causes

Cluster older than the chart requires

The chart needs APIs/features from a newer Kubernetes than the target cluster runs, so its kubeVersion floor is not met.

Detected version differs from intent

Helm reads the live cluster version; if CI points at an older cluster than expected, the constraint fails even when a newer cluster would pass.

How to fix it

Check cluster vs chart requirement

kubectl version --output=yaml | grep -A2 serverVersion
grep -i kubeVersion ./chart/Chart.yaml

Use a compatible cluster or chart version

1. Upgrade the cluster to satisfy the chart’s kubeVersion, or target a cluster that already does.
2. Or pin an older chart version whose kubeVersion your cluster meets.
3. For helm template offline, pass --kube-version to render against an intended version.

helm template my-release ./chart --kube-version 1.27.0

How to prevent it

• Keep clusters and charts on compatible Kubernetes versions.
• Pin chart versions tested against your cluster version.
• Assert the target cluster version early in the pipeline.

Frequently asked questions

Related guides

References

• Kubernetes documentation
• GitHub Actions documentation