What causes "error parsing name for manifest list %s: %w" in docker/cli?

Provide a valid `registry/repo[:tag]` name.

error parsing name for manifest list

Error message

error parsing name for manifest list %s: %w

What it means

Returned by `createManifestList` (create_list.go:40-43) when `normalizeReference(newRef)` fails on the first positional argument of `docker manifest create`. The manifest-list name must be a valid Docker reference (repository[:tag]). The %w wraps the distribution/reference parse error.

Solutions

Provide a valid `registry/repo[:tag]` name.
Quote the argument to avoid shell word-splitting.
Drop any URL scheme (`https://`) — use bare hostname.
Use lowercase repository components only.

Example fix

# before
docker manifest create 'https://reg.io/My List' img
# after
docker manifest create reg.io/mylist:1.0 img

Defensive patterns

Strategy: validation

Validate before calling

if _, err := reference.ParseNormalizedNamed(listName); err != nil {
    return fmt.Errorf("manifest-list name %q is not a valid reference: %w", listName, err)
}

Try / catch

if err := createManifestList(ctx, cli, args, opts); err != nil {
    if strings.HasPrefix(err.Error(), "error parsing name for manifest list") {
        return fmt.Errorf("first argument must be a valid repository[:tag]; got %q", args[0])
    }
    return err
}

Prevention

Validate the list name with distribution/reference before create.
Use lowercase, no scheme, no spaces.
Quote shell arguments.

When it happens

Trigger: Running `docker manifest create 'invalid name with spaces' img` or a name with illegal characters / uppercase. Also when the name lacks a tag (a default `:latest` is added, but parsing still requires a valid repository).

Common situations: Typos, unquoted shell expansion, pasting a URL with scheme (`https://...`), or exceeding the 256-char path component limit.

Related errors

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

Appendix: source

Thrown at cli/command/manifest/create_list.go:42

		Short: "Create a local manifest list for annotating and pushing to a registry",
		Args:  cli.RequiresMinArgs(2),
		RunE: func(cmd *cobra.Command, args []string) error {
			return createManifestList(cmd.Context(), dockerCLI, args, opts)
		},
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	flags.BoolVar(&opts.insecure, "insecure", false, "Allow communication with an insecure registry")
	flags.BoolVarP(&opts.amend, "amend", "a", false, "Amend an existing manifest list")
	return cmd
}

func createManifestList(ctx context.Context, dockerCLI command.Cli, args []string, opts createOpts) error {
	newRef := args[0]
	targetRef, err := normalizeReference(newRef)
	if err != nil {
		return fmt.Errorf("error parsing name for manifest list %s: %w", newRef, err)
	}

	manifestStore := newManifestStore(dockerCLI)
	_, err = manifestStore.GetList(targetRef)
	switch {
	case errdefs.IsNotFound(err):
		// New manifest list
	case err != nil:
		return err
	case !opts.amend:
		return errors.New("refusing to amend an existing manifest list with no --amend flag")
	}

	// Now create the local manifest list transaction by looking up the manifest schemas
	// for the constituent images:
	manifests := args[1:]
	for _, manifestRef := range manifests {
		namedRef, err := normalizeReference(manifestRef)

View on GitHub (pinned to 4f84911bfe)