kubernetes/kops · error

unable to parse kubernetes version %q

Error message

unable to parse kubernetes version %q

What it means

defaultImage in new_cluster.go parses cluster.Spec.KubernetesVersion with util.ParseKubernetesVersion; when that fails it wraps the failure as 'unable to parse kubernetes version'. It indicates the cluster's kubernetesVersion string is not a valid semantic version.

Source

Thrown at upup/pkg/fi/cloudup/new_cluster.go:1710

	return etcd
}

func addCiliumNetwork(cluster *api.Cluster) {
	cilium := &api.CiliumNetworkingSpec{}
	cluster.Spec.Networking.Cilium = cilium
	cilium.EnableNodePort = true
	if cluster.Spec.KubeProxy == nil {
		cluster.Spec.KubeProxy = &api.KubeProxyConfig{}
	}
	enabled := false
	cluster.Spec.KubeProxy.Enabled = &enabled
}

// defaultImage returns the default Image, based on the cloudprovider
func defaultImage(cluster *api.Cluster, channel *api.Channel, architecture architectures.Architecture) (string, error) {
	kubernetesVersion, err := util.ParseKubernetesVersion(cluster.Spec.KubernetesVersion)
	if err != nil {
		return "", fmt.Errorf("unable to parse kubernetes version %q", cluster.Spec.KubernetesVersion)
	}

	if channel != nil {
		image := channel.FindImage(cluster.GetCloudProvider(), *kubernetesVersion, architecture)
		if image != nil {
			return image.Name, nil
		}
	}

	switch cluster.GetCloudProvider() {
	case api.CloudProviderDO:
		return defaultDOImageNoble, nil
	case api.CloudProviderHetzner:
		return defaultHetznerImageNoble, nil
	case api.CloudProviderScaleway:
		return defaultScalewayImageNoble, nil
	case api.CloudProviderLinode:
		return defaultLinodeImageNoble, nil

View on GitHub (pinned to 4c8573c808)

Solutions

1. Set kubernetesVersion to a valid semver, e.g. 1.29.4 (try v-prefixed only if your kops version supports it)
2. Validate the version locally: `kops get cluster -o yaml` and inspect spec.kubernetesVersion
3. If using latestStable/alias resolution, resolve it to an explicit version first

Example fix

// before
kubernetesVersion: master
// after
kubernetesVersion: 1.29.4

if _, err := semver.Parse(strings.TrimPrefix(ver, "v")); err != nil {
    return fmt.Errorf("kubernetesVersion %q is not valid semver", ver)
}

When it happens

Trigger: Setting spec.kubernetesVersion to a non-semver string such as a channel alias, a branch name like "master", a value with a prefix like "v1.29.4" when the parser requires bare semver, or an empty/garbage value before defaultImage runs.

Common situations: Hand-edited cluster.yaml with a typo; using a placeholder version in templates; specifying a dev version like "1.30.0-alpha.1" with unexpected formatting; environment substitution leaving a literal variable in the manifest.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• unable to parse KubernetesVersion %q: %w
• error parsing version %q: %v
• unknown CNI plugin binaries asset: %s
• cannot parse KubernetesVersion %q: %w
• DeviceName not set for volume

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/1d183e88d336c6ee. Report an issue: GitHub.