What causes "unknown architecture %q" in GoogleContainerTools/skaffold?

Use GOARCH names: amd64, arm64, arm, 386, ppc64le, s390x, riscv64, etc.

unknown architecture %q

Error message

unknown architecture %q

What it means

Skaffold validates the architecture component of a platform string against known GOARCH values (copied from containerd/platforms). If the arch token is not in that list, isKnownArch returns this error. It uses GOARCH names like amd64 and arm64, not marketing names like x86_64 or aarch64.

Source

Thrown at pkg/skaffold/platform/platform.go:148

// isKnownOS returns an error if we don't know about the operating system.
// Unexported function copied from "github.com/containerd/containerd/platforms"
func isKnownOS(os string) error {
	switch os {
	case "aix", "android", "darwin", "dragonfly", "freebsd", "hurd", "illumos", "js", "linux", "nacl", "netbsd", "openbsd", "plan9", "solaris", "windows", "zos":
		return nil
	}
	return fmt.Errorf("unknown operating system %q", os)
}

// isKnownArch returns an error if we don't know about the architecture.
// Unexported function copied from "github.com/containerd/containerd/platforms"
func isKnownArch(arch string) error {
	switch arch {
	case "386", "amd64", "amd64p32", "arm", "armbe", "arm64", "arm64be", "ppc64", "ppc64le", "mips", "mipsle", "mips64", "mips64le", "mips64p32", "mips64p32le", "ppc", "riscv", "riscv64", "s390", "s390x", "sparc", "sparc64", "wasm":
		return nil
	}
	return fmt.Errorf("unknown architecture %q", arch)
}

func Format(pl specs.Platform) string { return platforms.Format(pl) }

View on GitHub (pinned to a1189de023)

Solutions

Use GOARCH names: amd64, arm64, arm, 386, ppc64le, s390x, riscv64, etc.
Replace x86_64 with amd64 and aarch64 with arm64 in the platform string
Test with a canonical platform value like linux/amd64 to isolate the bad token

Example fix

// before
skaffold build --platform linux/x86_64
// after
skaffold build --platform linux/amd64

Defensive patterns

Strategy: validation

Validate before calling

const knownArch = new Set(["386","amd64","amd64p32","arm","armbe","arm64","arm64be","ppc64","ppc64le","mips","mipsle","mips64","mips64le","mips64p32","mips64p32le","ppc","riscv","riscv64","s390","s390x","sparc","sparc64","wasm"]);
function validPlatformArch(p) { const parts = p.split("/"); return parts.length === 2 && knownArch.has(parts[1]); }

Type guard

function isKnownArch(arch) {
  return ["386","amd64","amd64p32","arm","armbe","arm64","arm64be","ppc64","ppc64le","mips","mipsle","mips64","mips64le","mips64p32","mips64p32le","ppc","riscv","riscv64","s390","s390x","sparc","sparc64","wasm"].includes(arch);
}

Try / catch

try {
  await skaffold.build({ platforms: [sel] });
} catch (e) {
  if (/unknown architecture/.test(String(e))) {
    throw new Error(`Bad arch in platform "${sel}"; use GOARCH names like amd64, not x86_64`);
  }
  throw e;
}

Prevention

Use GOARCH spellings: amd64 not x86_64, arm64 not aarch64, 386 not i386
Normalize machine output (uname -m) to GOARCH before building platform strings
Validate platform strings with a shared linter/checker in CI

When it happens

Trigger: A platform selection contains an unknown arch token, e.g. --platform linux/x86_64 or build.platforms: [linux/aarch64]; isKnownPlatform calls isKnownArch which falls through its switch.

Common situations: Writing x86_64 instead of amd64; aarch64 instead of arm64; armhf instead of arm; typos like am64; using 32-bit names like i386 instead of 386.

Related errors

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/be2efedcca05cee7. Report an issue: GitHub.