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

Use either a tag OR a digest, not both malformed together: `repo:tag` or `repo@sha256:...`.

annotate: error parsing name for manifest

Error message

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

What it means

Returned by `runManifestAnnotate` (annotate.go:130-133) when `normalizeReference(opts.image)` fails on the second positional argument (MANIFEST). Same parsing rules as the target: the source image must be a syntactically valid Docker reference. The %w wraps the distribution/reference parse error.

Solutions

Use either a tag OR a digest, not both malformed together: `repo:tag` or `repo@sha256:...`.
Validate the image name parses with a simple `docker pull --dry-run` style check or `docker manifest inspect <name>`.
Quote the argument and remove shell-special characters.
Ensure the repository component uses lowercase alphanumerics and allowed separators.

Example fix

# before
docker manifest annotate mylist 'My-Image:V1@bad'
# after
docker manifest annotate mylist myregistry.com/myimage:1.0

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Use either tag or digest form, not both malformed.
Validate with reference.ParseNormalizedNamed in your wrapper code.
Keep repository components lowercase.

When it happens

Trigger: Running `docker manifest annotate mylist 'bad:image:name:extra'` — too many colon-separated components, illegal characters, or an unparseable digest suffix.

Common situations: Pasting an image name with a trailing tag + digest simultaneously, illegal characters, or a malformed digest.

Related errors

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

Appendix: source

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

	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)
	}
	if opts.os != "" {
		imageManifest.Descriptor.Platform.OS = opts.os
	}

View on GitHub (pinned to 4f84911bfe)