docker/cli · error · invalidParameterErr

error parsing specified platform

Error message

error parsing specified platform: %w

What it means

Returned by createContainer() when the --platform flag value cannot be parsed by platforms.Parse (cli/command/container/create.go:313-317). The error is marked invalidParameter so the CLI treats it as a client-side usage error. platforms.Parse expects an OCI-style 'os[/arch[/variant]]' string; missing components are allowed but malformed separators, unknown tokens, or empty segments fail.

Solutions

1. Use the canonical 'os/arch[/variant]' form, e.g. --platform linux/amd64 or --platform linux/arm64/v8.
2. Remove trailing slashes and empty segments.
3. Verify the platform string with: docker run --rm --platform <value> alpine echo ok.
4. Check supported platforms for the image with docker manifest inspect <image>.

Example fix

# before
docker create --platform linux/amd64/extra myimage   # too many segments
# after
docker create --platform linux/amd64 myimage

// Validate a --platform string with the same parser the CLI uses.
func validatePlatform(p string) error {
    if p == "" { return nil }
    if _, err := platforms.Parse(p); err != nil {
        return fmt.Errorf("invalid --platform %q (expected os[/arch[/variant]]): %w", p, err)
    }
    return nil
}

// isParsablePlatform reports whether p parses as os[/arch[/variant]].
func isParsablePlatform(p string) bool {
    _, err := platforms.Parse(p)
    return err == nil
}

When it happens

Trigger: Passing --platform <value> to docker create/run with a value that platforms.Parse rejects: too many slash segments, empty segments ('linux//amd64'), or an otherwise malformed component. There is an earlier platforms.Parse at line 223 (without the invalidParameter wrap) used for a pre-check, but the canonical surfaced error is here.

Common situations: Typos like 'linux/amd64/extra', trailing/leading slashes, 'linux/', or pasting a full 'linux/amd64/v1' with an invalid variant. Also passing architecture-only values without an OS in contexts the parser rejects.

Related errors

• cannot attach to a stopped container, start it first
• cannot attach to a paused container, unpause it first
• cannot attach to a restarting container, wait until it is…
• source can not be empty
• destination can not be empty

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

Appendix: source

Thrown at cli/command/container/create.go:316

			// Resolve this here for later, ensuring we error our before we create the container.
			creds, err := readCredentials(dockerCLI)
			if err != nil {
				return "", fmt.Errorf("resolving credentials failed: %w", err)
			}
			if len(creds) > 0 {
				// Set our special little location for the config file.
				containerCfg.Config.Env = append(containerCfg.Config.Env, "DOCKER_CONFIG="+path.Dir(dockerConfigPathInContainer))

				apiSocketCreds = creds // inject these after container creation.
			}
		}
	}

	var platform *ocispec.Platform
	if options.platform != "" {
		p, err := platforms.Parse(options.platform)
		if err != nil {
			return "", invalidParameter(fmt.Errorf("error parsing specified platform: %w", err))
		}
		platform = &p
	}

	if options.pull == PullImageAlways {
		if err := pullImage(ctx, dockerCLI, config.Image, options); err != nil {
			return "", err
		}
	}

	hostConfig.ConsoleSize[0], hostConfig.ConsoleSize[1] = dockerCLI.Out().GetTtySize()

	response, err := dockerCLI.Client().ContainerCreate(ctx, client.ContainerCreateOptions{
		Name: options.name,
		// Image:            config.Image, // TODO(thaJeztah): pass image-ref separate
		Platform:         platform,
		Config:           config,
		HostConfig:       hostConfig,

View on GitHub (pinned to 4f84911bfe)