annotate: error parsing name for manifest list

Error message

annotate: error parsing name for manifest list %s: %w

What it means

Returned by `runManifestAnnotate` (annotate.go:126-129) when `normalizeReference(opts.target)` fails on the first positional argument (MANIFEST_LIST). normalizeReference calls `reference.ParseNormalizedNamed`, so the target name must be a valid Docker reference (repository[:tag|@digest]). The %w wraps the distribution/reference parse error.

Solutions

Pass a valid repository reference optionally with a tag: `registry/repo:tag`.
Quote the argument to avoid shell mangling of special characters.
Run `docker manifest create` first with the same name to confirm it parses.
Avoid uppercase characters and disallowed symbols in repository names.

Example fix

# before
docker manifest annotate 'My List!' img
# after
docker manifest annotate myregistry.com/mylist:1.0 img

Defensive patterns

Strategy: validation

Validate before calling

import "github.com/distribution/reference"
if _, err := reference.ParseNormalizedNamed(targetName); err != nil {
    return fmt.Errorf("MANIFEST_LIST name %q is not a valid reference: %w", targetName, err)
}

Try / catch

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

Prevention

Validate reference names with distribution/reference before invoking the command.
Quote arguments; avoid shell metacharacters.
Reuse the exact name used in `docker manifest create`.

When it happens

Trigger: Running `docker manifest annotate 'UPPERCASE Bad!' img` (uppercase invalid), a name with illegal characters, an empty name, or a name longer than the reference limit.

Common situations: Typos, shell unquoted special characters, copy-paste of a registry URL instead of a repository name, or trailing slash misuse.

Related errors

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

Appendix: source

Thrown at cli/command/manifest/annotate.go:128

		},
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()

	flags.StringVar(&opts.os, "os", "", "Set operating system")
	flags.StringVar(&opts.arch, "arch", "", "Set architecture")
	flags.StringVar(&opts.osVersion, "os-version", "", "Set operating system version")
	flags.StringSliceVar(&opts.osFeatures, "os-features", []string{}, "Set operating system feature")
	flags.StringVar(&opts.variant, "variant", "", "Set architecture variant")

	return cmd
}

func runManifestAnnotate(dockerCLI command.Cli, opts annotateOptions) error {
	targetRef, err := normalizeReference(opts.target)
	if err != nil {
		return fmt.Errorf("annotate: error parsing name for manifest list %s: %w", opts.target, err)
	}
	imgRef, err := normalizeReference(opts.image)
	if err != nil {
		return fmt.Errorf("annotate: error parsing name for manifest %s: %w", opts.image, err)
	}

	manifestStore := newManifestStore(dockerCLI)
	imageManifest, err := manifestStore.Get(targetRef, imgRef)
	switch {
	case errdefs.IsNotFound(err):
		return fmt.Errorf("manifest for image %s does not exist in %s", opts.image, opts.target)
	case err != nil:
		return err
	}

	// Update the mf
	if imageManifest.Descriptor.Platform == nil {
		imageManifest.Descriptor.Platform = new(ocispec.Platform)

View on GitHub (pinned to 4f84911bfe)