kubernetes/kops · error

unsupported distro %q

Error message

unsupported distro %q

What it means

After parsing /etc/os-release, FindDistribution builds a distro string like "ID-VERSION_ID" and matches it against a whitelist of supported distributions. If the string matches no case (e.g. "fedora-40", "alpine-3.20", an unrecognized major version like "rocky-11"), it logs the os-release contents at V(2) and returns this error. The file was readable, but the distro is simply not one kOps supports.

Source

Thrown at util/pkg/distributions/identify.go:112

	}
	if strings.HasPrefix(distro, "rhel-9.") {
		return DistributionRhel9, nil
	}
	if strings.HasPrefix(distro, "rhel-10.") {
		return DistributionRhel10, nil
	}
	if strings.HasPrefix(distro, "rocky-8.") {
		return DistributionRocky8, nil
	}
	if strings.HasPrefix(distro, "rocky-9.") {
		return DistributionRocky9, nil
	}
	if strings.HasPrefix(distro, "rocky-10.") {
		return DistributionRocky10, nil
	}
	// Some distros are not supported
	klog.V(2).Infof("Contents of /etc/os-release:\n%s", osReleaseBytes)
	return Distribution{}, fmt.Errorf("unsupported distro %q", distro)
}

View on GitHub (pinned to 4c8573c808)

Solutions

1. Switch nodes to a supported distro image (debian, ubuntu, rocky, flatcar, amazon-linux, etc.)
2. Enable klog V(2) to see the /etc/os-release contents logged with the error and confirm what distro/version string was produced
3. If the distro is a supported one at a new version, upgrade kOps — newer releases add new version cases (e.g. rocky-10)
4. If you fork kOps, add a case to the distro switch in identify.go for your ID-VERSION_ID

Example fix

// before
# cluster.yaml node image: Fedora-Cloud-Base-40
// after
# node image: Ubuntu 22.04 (or another supported distro)

// pre-flight: identify and reject unsupported distros before provisioning
name := getDistroFromImage(nodeImage) // resolve before booting nodes
supported := []string{"ubuntu", "debian", "rocky", "flatcar", "amazon"}
if !slices.ContainsFunc(supported, func(s string) bool { return strings.HasPrefix(name, s) }) {
    return fmt.Errorf("node image distro %q is not supported by this kOps version", name)
}

func isSupportedDistroString(distro string) bool {
    switch {
    case strings.HasPrefix(distro, "ubuntu-"), strings.HasPrefix(distro, "debian-"),
        strings.HasPrefix(distro, "rocky-"), strings.HasPrefix(distro, "flatcar"),
        strings.HasPrefix(distro, "amazon-linux"):
        return true
    }
    return false
}

distro, err := distributions.FindDistribution("/")
if err != nil {
    klog.V(2).Infof("os-release contents: %v", osReleaseBytes) // re-check what was seen
    return fmt.Errorf("this OS is not supported by kOps: %w; use a supported distro image", err)
}

When it happens

Trigger: Calling FindDistribution on a host whose ID=VERSION_ID combination has no case in the switch — e.g. alpine, fedora, opensuse, an EOL/renamed distro, or a version not yet in the list (e.g. rocky-11 or a new ubuntu point release that maps differently). Called from Run, Find, RenderLocal, systemdSystemPath.

Common situations: Testing kOps/nodeup on a developer laptop running Fedora or Arch; using an experimental community AMI built on an unsupported distro; a distro version bump (e.g. centos 8 -> stream) that changed the ID/VERSION_ID; Alpine-based minimal images for nodes.

Related errors

• unknown distro %v
• unknown CNI plugin binaries asset: %s
• invalid networking option %s. Kubenet does not support priva
• error determining OS architecture: %v
• error determining OS distribution: %v

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