Helm "chart requires kubeVersion" not compatible in CI

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".

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.

# 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.

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.

Related guides