What causes "unsupported arch: %q" in kubernetes/kops?

Rebuild or download kOps for a supported architecture: use the official amd64 or arm64 release binaries

unsupported arch: %q

Error message

unsupported arch: %q

What it means

FindArchitecture in util/pkg/architectures maps the Go runtime's runtime.GOARCH to kOps' internal Architecture type, which only supports amd64 and arm64. If the kOps binary was compiled for any other CPU architecture (e.g. 386, arm, ppc64le, s390x, riscv64), the function cannot return a valid Architecture and throws this error. It signals that the binary itself was built for a platform kOps does not target.

Source

Thrown at util/pkg/architectures/architectures.go:47

const (
	ArchitectureAmd64 Architecture = "amd64"
	ArchitectureArm64 Architecture = "arm64"
)

type GPUVendor string

const (
	GPUVendorNvidia GPUVendor = "nvidia"
)

func FindArchitecture() (Architecture, error) {
	switch runtime.GOARCH {
	case "amd64":
		return ArchitectureAmd64, nil
	case "arm64":
		return ArchitectureArm64, nil
	default:
		return "", fmt.Errorf("unsupported arch: %q", runtime.GOARCH)
	}
}

func GetSupported() []Architecture {
	// Kubernetes PR builds only generate AMD64 binaries at the moment
	// Force support only for AMD64 or ARM64
	arch := os.Getenv("KOPS_ARCH")
	if arch != "" {
		switch arch {
		case "amd64":
			return []Architecture{ArchitectureAmd64}
		case "arm64":
			return []Architecture{ArchitectureArm64}
		default:
			klog.Warningf("unknown architecture KOPS_ARCH=%q", arch)
		}
	}

View on GitHub (pinned to 4c8573c808)

Solutions

Rebuild or download kOps for a supported architecture: use the official amd64 or arm64 release binaries
If the host truly has an unsupported CPU, run kOps remotely (e.g. from a laptop or CI amd64 runner) against the cluster instead of on the node itself
If cross-compiling, explicitly set GOARCH=amd64 (or arm64) in your build command/Makefile
Check the binary with `go version -m $(which kops)` to see the GOARCH it was built for

Example fix

// before (cross-compiling in CI)
goos=linux goarch=386 go build -o kops .
// after
goos=linux goarch=amd64 go build -o kops .

Defensive patterns

Strategy: validation

Validate before calling

supported := architectures.GetSupported() // honors KOPS_ARCH
// before calling FindArchitecture, check the binary's own arch:
if runtime.GOARCH != "amd64" && runtime.GOARCH != "arm64" {
    return fmt.Errorf("this host arch %s is not supported; build kOps for amd64/arm64", runtime.GOARCH)
}

Type guard

func isSupportedArch(a string) bool {
    return a == "amd64" || a == "arm64"
}

Try / catch

arch, err := architectures.FindArchitecture()
if err != nil {
    klog.Fatalf("cannot run kOps on this platform: %v (supported: %v)", err, architectures.GetSupported())
}

Prevention

Download official release binaries for amd64/arm64 instead of building for exotic GOARCH targets
Pin GOARCH explicitly in CI/Makefiles so cross-compilation cannot silently pick an unsupported arch
Check `go version -m kops` to verify build arch when distributing binaries
Run kOps from an amd64/arm64 control machine against remote clusters rather than on the node itself

When it happens

Trigger: Calling architectures.FindArchitecture() from a kOps binary compiled with GOARCH set to anything other than amd64 or arm64 — e.g. running `GOARCH=386 go build` output on an i386 host, or building for arm/armhf/ppc64le. It is reached via Run in the CLI before any cluster work begins.

Common situations: Running kOps on old 32-bit hosts or embedded boards; a Makefile or CI job cross-compiling with an unintended GOARCH; distro-packaged kOps built for secondary architectures (ppc64le, s390x) that upstream never supported; using `go install` on a machine whose native arch is unsupported.

Related errors

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