kubernetes/kops · error

unknown or unsupported distro: %v

Error message

unknown or unsupported distro: %v

What it means

nodeup's Service task resolves the systemd unit directory by detecting the Linux distribution at runtime via distributions.FindDistribution("/"). When that detection itself fails (it cannot identify the OS from /etc/os-release or equivalents), the task wraps the underlying error as "unknown or unsupported distro" and aborts, because it cannot know where to write unit files.

Source

Thrown at upup/pkg/fi/nodeup/nodetasks/service.go:169

	properties := make(map[string]string)
	for _, line := range strings.Split(string(output), "\n") {
		if line == "" {
			continue
		}
		tokens := strings.SplitN(line, "=", 2)
		if len(tokens) != 2 {
			klog.Warningf("Ignoring line in systemd show output: %q", line)
			continue
		}
		properties[tokens[0]] = tokens[1]
	}
	return properties, nil
}

func (_ *Service) systemdSystemPath() (string, error) {
	d, err := distributions.FindDistribution("/")
	if err != nil {
		return "", fmt.Errorf("unknown or unsupported distro: %v", err)
	}

	if d.IsDebianFamily() {
		return debianSystemdSystemPath, nil
	} else if d.IsRHELFamily() {
		return centosSystemdSystemPath, nil
	} else if d == distributions.DistributionFlatcar {
		return flatcarSystemdSystemPath, nil
	} else if d == distributions.DistributionContainerOS {
		return containerosSystemdSystemPath, nil
	} else {
		return "", fmt.Errorf("unsupported systemd system")
	}
}

func (e *InstallService) Find(_ *fi.InstallContext) (*InstallService, error) {
	actual, err := e.Service.Find(nil)
	if actual == nil || err != nil {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Verify /etc/os-release exists on the node image and contains valid ID/ID_LIKE fields
2. Use a kOps-supported OS image (Debian/Ubuntu, RHEL-family, Flatcar, Container-Optimized OS)
3. If building a custom image, base it on a supported distro family so ID_LIKE maps to debian or rhel
4. Check nodeup version against supported OS matrix; older nodeup may not know newer distro releases

Example fix

# before (broken node image)
$ ls /etc/os-release
ls: cannot access '/etc/os-release': No such file or directory
// after: bake a supported base image so /etc/os-release exists
// e.g. Dockerfile FROM debian:bookworm (which ships /etc/os-release)

// Run on the node before nodeup:
if [ ! -f /etc/os-release ]; then echo 'os-release missing; unsupported distro' >&2; exit 1; fi
. /etc/os-release; echo "$ID $ID_LIKE"

// Go caller of nodeup internals
if _, err := svc.systemdSystemPath(); err != nil {
	if strings.Contains(err.Error(), "unknown or unsupported distro") {
		return fmt.Errorf("node image not supported: %w", err)
	}
	return err
}

When it happens

Trigger: Service.Find or Service.RenderLocal runs on a node whose root filesystem lacks a recognizable /etc/os-release (or the detection helper returns an error), so systemdSystemPath cannot map the distro to debianSystemdSystemPath / centosSystemdSystemPath / flatcar / COS paths.

Common situations: Bootstrapping nodes on unofficial or custom minimal images (e.g. hand-built images with the os-release file stripped), niche distros not in kOps' supported list (Alpine, Arch), or a corrupted/missing /etc/os-release after image hardening.

Related errors

• unsupported systemd system
• error building kubelet flags: %v
• failed to create bpf mount unit: %w
• failed to create cgroupv2 mount unit: %w
• error determining OS architecture: %v

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