docker/cli · error

refusing to amend an existing manifest list with no --amend

Error message

refusing to amend an existing manifest list with no --amend flag

What it means

docker manifest create builds a local manifest list. In createManifestList (cli/command/manifest/create_list.go:46-53), the CLI first checks the local manifest store: if a list with the target name already exists (GetList returns no error) and --amend was not passed, it refuses to silently overwrite or modify the existing list. --amend is the explicit opt-in to update an existing manifest list.

Source

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

	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)
		if err != nil {
			// TODO: wrap error?
			return err
		}

		manifest, err := getManifest(ctx, dockerCLI, targetRef, namedRef, opts.insecure)
		if err != nil {
			return err
		}
		if err := manifestStore.Save(targetRef, namedRef, manifest); err != nil {
			return err

View on GitHub (pinned to e9452d6e78)

Solutions

1. Add --amend to update the existing list: docker manifest create --amend myrepo/app:tag img1 img2
2. Or remove the stale local list first: docker manifest rm myrepo/app:tag
3. Use docker manifest push --purge in scripts so the local list is deleted after a successful push
4. Consider docker buildx imagetools create, which handles multi-arch manifest creation without local store state

Example fix

# before
docker manifest create myrepo/app:1.0 myrepo/app:1.0-amd64 myrepo/app:1.0-arm64
# after (list already exists locally)
docker manifest create --amend myrepo/app:1.0 myrepo/app:1.0-amd64 myrepo/app:1.0-arm64

When it happens

Trigger: Running `docker manifest create myrepo/app:tag img1 img2` when a manifest list named myrepo/app:tag already exists in the local manifest store (~/.docker/manifests) from a previous docker manifest create that was never pushed/purged.

Common situations: Re-running a multi-arch build script after a failed or partial `docker manifest push` (push --purge removes the local list, plain runs may leave it); iterating locally on a manifest list; CI runners with persistent home directories accumulating stale local manifest lists.

Related errors

• failed to parse hook template
• unexpected hook response type:
• plugin candidate path cannot be empty
• plugin SchemaVersion version cannot be empty
• plugin server is closed

AI-assisted analysis of docker/cli@e9452d6e78 (2026-08-01). Data as JSON: /data/errors/35ad11c594dfcd88.json. Report an issue: GitHub.