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

createManifestList() looks up the target ref in the local manifest store; if a list already exists and the user did not pass --amend/-a, it refuses to silently clobber an in-progress manifest list. errdefs.IsNotFound proceeds (new list); any other existing-list case requires --amend.

Solutions

1. Add --amend/-a to append to the existing list
2. Remove the existing local list first and recreate it cleanly
3. Check for an existing list before deciding to create vs amend

Example fix

// before
docker manifest create myrepo/mylist:latest img1 img2
// after
docker manifest create --amend myrepo/mylist:latest img1 img2

manifestStore := newManifestStore(dockerCLI)
if _, err := manifestStore.GetList(targetRef); err == nil {
    // list exists — caller must decide: amend or recreate
    if !opts.amend { opts.amend = true /* or abort */ }
}

func listExists(store ManifestStore, ref string) bool {
    _, err := store.GetList(ref)
    return err == nil
}

err := createManifestList(ctx, cli, args, opts)
if err != nil && strings.Contains(err.Error(), "refusing to amend") {
    // retry with --amend, or remove the list first then recreate
    opts.amend = true
    err = createManifestList(ctx, cli, args, opts)
}
return err

When it happens

Trigger: Running `docker manifest create <list> ...` a second time after the list was already created locally, without --amend.

Common situations: Retrying a partially-built manifest list; CI re-running a create step; iterating on a manifest assembly.

Related errors

• tag can't be used with --all-tags/-a
• tag can't be used with --all-tags/-a
• cannot use source images from a different registry than the…
• unrecognized config key
• invalid key/value pair format in driver options

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

Appendix: 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 4f84911bfe)