kubernetes/kops · error

error determining OS distribution: %v

Error message

error determining OS distribution: %v

What it means

nodeup identifies the node's OS distribution (e.g. Ubuntu, Debian, Flatcar, RockyLinux) by inspecting / via distributions.FindDistribution("/"), which reads /etc/os-release and similar files. This error means detection failed, so nodeup cannot pick distribution-specific packages, systemd units, or file layouts. Run aborts before building the model.

Source

Thrown at upup/pkg/fi/nodeup/command.go:179

	if bootConfig.NodeupConfigHash != "" {
		if want, got := bootConfig.NodeupConfigHash, base64.StdEncoding.EncodeToString(nodeupConfigHash[:]); got != want {
			return fmt.Errorf("nodeup config hash mismatch (was %q, expected %q)", got, want)
		}
	}

	err = evaluateSpec(&nodeupConfig, bootConfig.CloudProvider, region)
	if err != nil {
		return err
	}

	architecture, err := architectures.FindArchitecture()
	if err != nil {
		return fmt.Errorf("error determining OS architecture: %v", err)
	}

	distribution, err := distributions.FindDistribution("/")
	if err != nil {
		return fmt.Errorf("error determining OS distribution: %v", err)
	}

	configAssets := nodeupConfig.Assets[architecture]
	assetStore := fi.NewAssetStore(c.CacheDir)
	for _, asset := range configAssets {
		err := assetStore.Add(ctx, asset)
		if err != nil {
			return fmt.Errorf("error adding asset %q: %v", asset, err)
		}
	}

	// cloud holds the AWS clients, on AWS only.
	var cloud *awsup.Cloud

	if bootConfig.CloudProvider == api.CloudProviderAWS {
		cloud, err = awsup.NewCloud(ctx, region)
		if err != nil {
			return err

View on GitHub (pinned to 4c8573c808)

Solutions

1. Ensure /etc/os-release exists and is populated on the node image (restore it from the distro's base-files/os-release package).
2. Use a kOps-supported OS image (Ubuntu, Debian, RockyLinux/RHEL, Flatcar, AmazonLinux) for the instance group via 'kops create instancegroup' / image setting.
3. Upgrade kOps if the distro version is newer than the release supports (e.g. brand-new Ubuntu LTS).
4. Verify the root filesystem is mounted and readable (FindDistribution is called with "/") — check mount namespace issues in containerized invocations.

Example fix

// before: Dockerfile-based node image stripped of os-release
RUN rm -f /etc/os-release
// after: keep distro identification files intact
# do not remove /etc/os-release; nodeup requires it

// Confirm /etc/os-release exists and is parseable before running nodeup
b, err := os.ReadFile("/etc/os-release")
if err != nil {
    return fmt.Errorf("node image missing /etc/os-release: %w", err)
}
if !strings.Contains(string(b), "ID=") {
    return fmt.Errorf("/etc/os-release is malformed")
}

err := cmd.Run(out)
if err != nil && strings.Contains(err.Error(), "error determining OS distribution") {
    // switch to a kOps-supported OS image for the instance group
}

When it happens

Trigger: Calling NodeUpCommand.Run() on a host whose root filesystem lacks the files FindDistribution relies on — missing or empty /etc/os-release, an unsupported distribution string, or an unreadable root — during the detection step at command.go:177.

Common situations: Custom/minimal base images (distroless, custom AMIs) without /etc/os-release; very new or very old distro versions unsupported by the kOps release; containers with an incomplete root filesystem; heavily stripped OS images.

Related errors

• error determining OS architecture: %v
• building nodeConfig for instanceGroup: %w
• unsupported cloud provider for authenticator %q
• no keypairID for %q
• challenge not set

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