What causes "unknown operating system %q" in GoogleContainerTools/skaffold?

Use GOOS names: linux, darwin, windows, freebsd, solaris, etc.

unknown operating system %q

Error message

unknown operating system %q

What it means

Skaffold validates the OS component of a platform string against the list of known GOOS values (copied from containerd/platforms). If the OS token is not in that list, isKnownOS returns this error and platform matching fails. Note it uses GOOS names like darwin, not marketing names like macos or osx.

Source

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

func isKnownPlatform(p specs.Platform) error {
	if err := isKnownOS(p.OS); err != nil {
		return err
	}
	if err := isKnownArch(p.Architecture); err != nil {
		return err
	}
	return nil
}

// 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 GOOS names: linux, darwin, windows, freebsd, solaris, etc.
Replace macos/osx with darwin and win32 with windows in your platform string
Check the full platform with a known-good value first, e.g. linux/amd64, then adjust

Example fix

// before (skaffold.yaml)
build:
  platforms: ["macos/arm64"]
// after
build:
  platforms: ["darwin/arm64"]

Defensive patterns

Strategy: validation

Validate before calling

const knownOS = new Set(["aix","android","darwin","dragonfly","freebsd","hurd","illumos","js","linux","nacl","netbsd","openbsd","plan9","solaris","windows","zos"]);
function validPlatformOS(p) { const os = p.split("/")[0]; return knownOS.has(os); }

Type guard

function isKnownOS(os) {
  return ["aix","android","darwin","dragonfly","freebsd","hurd","illumos","js","linux","nacl","netbsd","openbsd","plan9","solaris","windows","zos"].includes(os);
}

Try / catch

try {
  await skaffold.build({ platforms: [sel] });
} catch (e) {
  if (/unknown operating system/.test(String(e))) {
    throw new Error(`Bad OS in platform "${sel}"; use GOOS names like darwin, not macos`);
  }
  throw e;
}

Prevention

Always use GOOS spellings: darwin not macos/osx, windows not win32
Validate platform strings in CI before invoking skaffold
Cross-check against `go tool dist list` for valid OS/arch pairs

When it happens

Trigger: A platform selection contains an unknown OS token, e.g. skaffold --platform linux/bogus or build.platforms: [macos/amd64] in skaffold.yaml; isKnownPlatform calls isKnownOS which falls through its switch.

Common situations: Writing macos or osx instead of darwin; writing win or win32 instead of windows; typos like linx; copying a Docker --platform value that uses non-GOOS naming.

Related errors

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