docker/cli · error

invalid platform

Error message

invalid platform: %w

What it means

Returned by runHistory (history.go:64) when platforms.Parse rejects the --platform flag value for 'docker image history'. The platform string must follow the 'os[/arch[/variant]]' form (e.g., 'linux/amd64'). Parse fails on empty OS, unknown component separators, or malformed tokens. This is the same validator used across build/load/save.

Solutions

1. Use the canonical form 'os/arch[/variant]': '--platform linux/amd64'.
2. If you only know the architecture, prepend the OS: 'linux/' + arch.
3. List supported platforms with 'docker image inspect --format '{{.Os}}/{{.Architecture}}' <image>'.
4. Drop --platform entirely to let the daemon pick the default.

Example fix

# before
docker image history --platform amd64 nginx
# after
docker image history --platform linux/amd64 nginx

// Validate a platform string before passing it to --platform.
import "github.com/containerd/platforms"

func validatePlatform(p string) error {
	_, err := platforms.Parse(p)
	return err
}

if err := cmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "invalid platform") {
		// re-prompt for a correctly formatted os/arch[/variant] string
	}
}

When it happens

Trigger: Running 'docker image history --platform <bad> <image>' where <bad> is empty-ish, has extra slashes, a missing OS, or non-identifier characters. Examples: '--platform amd64' (missing OS), '--platform linux/extra/v8/wrong' (too many parts), '--platform /amd64' (empty OS).

Common situations: Forgetting the OS and passing only the architecture ('--platform amd64'); using full OCI image platform strings with unexpected fields; copy-pasting a platform string from a multi-arch manifest that includes OS features/variants in an unsupported order; trailing slashes.

Related errors

• invalid platform
• invalid platform
• error parsing specified platform
• manifest entry for image has unsupported os/arch combination
• invalid image reference for service

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

Appendix: source

Thrown at cli/command/image/history.go:64

	flags := cmd.Flags()

	flags.BoolVarP(&opts.human, "human", "H", true, "Print sizes and dates in human readable format")
	flags.BoolVarP(&opts.quiet, "quiet", "q", false, "Only show image IDs")
	flags.BoolVar(&opts.noTrunc, "no-trunc", false, "Don't truncate output")
	flags.StringVar(&opts.format, "format", "", flagsHelper.FormatHelp)
	flags.StringVar(&opts.platform, "platform", "", `Show history for the given platform. Formatted as "os[/arch[/variant]]" (e.g., "linux/amd64")`)
	_ = flags.SetAnnotation("platform", "version", []string{"1.48"})

	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms())
	return cmd
}

func runHistory(ctx context.Context, dockerCli command.Cli, opts historyOptions) error {
	var options []client.ImageHistoryOption
	if opts.platform != "" {
		p, err := platforms.Parse(opts.platform)
		if err != nil {
			return fmt.Errorf("invalid platform: %w", err)
		}
		options = append(options, client.ImageHistoryWithPlatform(p))
	}

	history, err := dockerCli.Client().ImageHistory(ctx, opts.image, options...)
	if err != nil {
		return err
	}

	format := opts.format
	if len(format) == 0 {
		format = formatter.TableFormatKey
	}

	historyCtx := formatter.Context{
		Output: dockerCli.Out(),
		Format: newHistoryFormat(format, opts.quiet, opts.human),
		Trunc:  !opts.noTrunc,

View on GitHub (pinned to 4f84911bfe)