manifest entry for image has unsupported os/arch combination

Error message

manifest entry for image has unsupported os/arch combination: %s/%s

What it means

Returned by `runManifestAnnotate` (annotate.go:164-166) when `isValidOSArch(os, arch)` returns false after applying the --os/--arch flags. The function checks the os/arch pair against a fixed allowlist (util.go `validOSArches`). Note the error prints `opts.os`/`opts.arch` (the raw flag values), so if flags were empty the message may show empty strings even though the stored Platform was used for validation — a known quirk.

Solutions

Use an OS/arch combination present in the validOSArches table (e.g. linux/amd64, linux/arm64, linux/arm, windows/amd64).
Upgrade the Docker CLI — newer versions extend the allowlist with more platforms.
Double-check spelling of the arch value (amd64 not amd644, arm64 not arm64v8).
If you genuinely need an unsupported pair, build a custom CLI or open an issue to extend the table.

Example fix

# before
docker manifest annotate mylist img --os linux --arch mips64
# after (verify support; mips64le may be supported in newer CLI)
docker manifest annotate mylist img --os linux --arch arm64

Defensive patterns

Strategy: validation

Validate before calling

// validate os/arch against the CLI's known set before annotating
if !isValidOSArch(osVal, archVal) {
    return fmt.Errorf("unsupported os/arch %s/%s; pick a supported pair (e.g. linux/amd64)", osVal, archVal)
}

Type guard

func supportedOSArch() map[[2]string]bool {
    // mirror util.go validOSArches; return the supported set for UI checks
    return map[[2]string]bool{{"linux","amd64"}:true, {"linux","arm64"}:true, {"windows","amd64"}:true /* ... */}
}

Try / catch

if err := runManifestAnnotate(cli, opts); err != nil {
    if strings.Contains(err.Error(), "unsupported os/arch combination") {
        return fmt.Errorf("%w — see supported platforms in the manifest docs", err)
    }
    return err
}

Prevention

Pick os/arch from the documented supported set.
Upgrade the CLI to get newer platforms.
Double-check arch spelling (amd64, arm64, arm).

When it happens

Trigger: Running `docker manifest annotate list img --os freebsd --arch mips` where `freebsd/mips` is not in the supported set, or `--os linux --arch mips` (mips not listed). Supported pairs include linux/amd64, linux/arm64, windows/amd64, etc.

Common situations: Targeting an OS/arch the CLI's allowlist doesn't recognize (older CLI versions, niche platforms like loong64/riscv64 not yet added), or typos in arch names (amd644).

Related errors

AI-assisted analysis of docker/cli@4f84911bfe (2026-08-07). Data as JSON: /api/errors/eda4ece98639da49. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/manifest/annotate.go:165

	}
	if opts.os != "" {
		imageManifest.Descriptor.Platform.OS = opts.os
	}
	if opts.arch != "" {
		imageManifest.Descriptor.Platform.Architecture = opts.arch
	}
	for _, osFeature := range opts.osFeatures {
		imageManifest.Descriptor.Platform.OSFeatures = appendIfUnique(imageManifest.Descriptor.Platform.OSFeatures, osFeature)
	}
	if opts.variant != "" {
		imageManifest.Descriptor.Platform.Variant = opts.variant
	}
	if opts.osVersion != "" {
		imageManifest.Descriptor.Platform.OSVersion = opts.osVersion
	}

	if !isValidOSArch(imageManifest.Descriptor.Platform.OS, imageManifest.Descriptor.Platform.Architecture) {
		return fmt.Errorf("manifest entry for image has unsupported os/arch combination: %s/%s", opts.os, opts.arch)
	}
	return manifestStore.Save(targetRef, imgRef, imageManifest)
}

func appendIfUnique(list []string, str string) []string {
	if slices.Contains(list, str) {
		return list
	}
	return append(list, str)
}

View on GitHub (pinned to 4f84911bfe)