docker/cli · error

invalid platform

Error message

invalid platform: %w

What it means

Returned by runSave (save.go:62) when platforms.Parse rejects one of the --platform values for 'docker image save'. Identical validator and flag semantics to load/history: a comma-separated list of 'os[/arch[/variant]]' tokens, each parsed in turn; the first failure aborts.

Solutions

1. Format each platform as 'os/arch[/variant]': '--platform linux/amd64'.
2. Strip malformed tokens from the comma-separated list.
3. Confirm available platforms: 'docker buildx imagetools inspect <image>'.
4. Drop --platform to save all platforms.

Example fix

# before
docker image save --platform amd64 -o out.tar nginx
# after
docker image save --platform linux/amd64 -o out.tar nginx

// Validate each platform in a comma-separated --platform list before saving.
func validatePlatforms(list []string) error {
	for _, p := range list {
		if _, err := platforms.Parse(p); err != nil {
			return fmt.Errorf("invalid platform %q: %w", p, err)
		}
	}
	return nil
}

if err := cmd.Execute(); err != nil {
	if strings.Contains(err.Error(), "invalid platform") {
		// correct the platform list and re-run save
	}
}

When it happens

Trigger: Running 'docker image save --platform <bad> -o out.tar <image>' where any element is malformed (missing OS, extra slashes, empty tokens). Save then proceeds to request only the validated platforms from the daemon.

Common situations: Passing arch-only values ('--platform amd64'); wrong separator or casing; copy-pasting a platform string that includes OS features or an unexpected variant component; trailing comma yielding an empty platform token.

Related errors

• invalid platform
• invalid platform
• error parsing specified platform
• failed to save image
• manifest entry for image has unsupported os/arch combination

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

Appendix: source

Thrown at cli/command/image/save.go:62

	flags := cmd.Flags()

	flags.StringVarP(&opts.output, "output", "o", "", "Write to a file, instead of STDOUT")
	flags.StringSliceVar(&opts.platform, "platform", []string{}, `Save only the given platform(s). Formatted as a comma-separated list of "os[/arch[/variant]]" (e.g., "linux/amd64,linux/arm64/v8")`)
	_ = flags.SetAnnotation("platform", "version", []string{"1.48"})

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

// runSave performs a save against the engine based on the specified options
func runSave(ctx context.Context, dockerCLI command.Cli, opts saveOptions) error {
	var options []client.ImageSaveOption

	platformList := []ocispec.Platform{}
	for _, p := range opts.platform {
		pp, err := platforms.Parse(p)
		if err != nil {
			return fmt.Errorf("invalid platform: %w", err)
		}
		platformList = append(platformList, pp)
	}
	if len(platformList) > 0 {
		options = append(options, client.ImageSaveWithPlatforms(platformList...))
	}

	var output io.Writer
	if opts.output == "" {
		if dockerCLI.Out().IsTerminal() {
			return errors.New("cowardly refusing to save to a terminal. Use the -o flag or redirect")
		}
		output = dockerCLI.Out()
	} else {
		writer, err := atomicwriter.New(opts.output, 0o600)
		if err != nil {
			return fmt.Errorf("failed to save image: %w", err)
		}

View on GitHub (pinned to 4f84911bfe)