docker/cli · error

invalid platform

Error message

invalid platform: %w

What it means

Returned by runLoad (load.go:86) when platforms.Parse rejects one of the --platform values for 'docker image load'. The flag accepts a comma-separated list (via StringSliceVar) and each entry is parsed independently; the first malformed entry aborts the load. Valid form is 'os[/arch[/variant]]'.

Solutions

1. Format each platform as 'os/arch[/variant]': '--platform linux/amd64,linux/arm64'.
2. Remove any malformed entries from the comma-separated list.
3. Validate each token against the image's manifest before loading.
4. Omit --platform to load all platforms.

Example fix

# before
docker image load --platform amd64,arm64 -i image.tar
# after
docker image load --platform linux/amd64,linux/arm64 -i image.tar

// Validate each platform in a comma-separated --platform list.
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") {
		// one of the comma-separated platforms is malformed; correct the list
	}
}

When it happens

Trigger: Running 'docker image load --platform <bad>[,<bad>]' where any element is malformed: missing OS, too many slash-separated parts, empty tokens, or non-identifier characters. Because the flag is a slice, a single bad entry among several fails the whole invocation.

Common situations: Passing '--platform amd64' (arch only, no OS); mixing a correct 'linux/amd64' with a malformed 'x86'; copy-pasting a manifest platform string with extra fields; trailing commas producing an empty element.

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/025b241597ee1ce9. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/image/load.go:86

		// depleting the standby list un-necessarily. On Linux, this equates to a regular os.Open.
		file, err := sequential.Open(opts.input)
		if err != nil {
			return err
		}
		defer func() { _ = file.Close() }()
		input = file
	}

	var options []client.ImageLoadOption
	if opts.quiet || !dockerCli.Out().IsTerminal() {
		options = append(options, client.ImageLoadWithQuiet(true))
	}

	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.ImageLoadWithPlatforms(platformList...))
	}

	res, err := dockerCli.Client().ImageLoad(ctx, input, options...)
	if err != nil {
		return err
	}
	defer func() { _ = res.Close() }()

	return jsonstream.Display(ctx, res, dockerCli.Out())
}

View on GitHub (pinned to 4f84911bfe)