Helm "chart requires kubeVersion" not compatible in CI

By Daniel Zoghalchali·Latchkey

The chart's Chart.yaml declares a kubeVersion constraint and the target cluster's version does not satisfy it. Helm refuses to install rather than render manifests the cluster may not support.

What this error means

helm install/upgrade fails with "Error: chart requires kubeVersion: >=1.27.0-0 which is incompatible with Kubernetes v1.25.x".

helm

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

Common causes

The cluster is older than the chart requires

The chart needs a newer Kubernetes API than the target cluster (often a CI test cluster) provides.

A subchart raises the requirement

A dependency declares a stricter kubeVersion that propagates to the umbrella chart.

How to fix it

Target a cluster that meets the constraint

Upgrade the cluster, or in CI provision a kind/k3s version that satisfies the chart's kubeVersion.

Terminal

# example: pin the kind node image to a supported version
kind create cluster --image kindest/node:v1.27.3

Render without a cluster to verify locally

Use helm template --kube-version to render against an assumed version when there is no live cluster, then confirm the real target meets the constraint.

Terminal

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

How to prevent it

Match CI test clusters to the Kubernetes version the chart supports.
Track subchart kubeVersion constraints when bumping dependencies.
Document the minimum cluster version your chart needs.

Frequently asked questions

What causes ""chart requires kubeVersion""?