{"id":"35ad11c594dfcd88","repo":"docker/cli","slug":"refusing-to-amend-an-existing-manifest-list-with-n","errorCode":null,"errorMessage":"refusing to amend an existing manifest list with no --amend flag","messagePattern":"refusing to amend an existing manifest list with no --amend flag","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/manifest/create_list.go","lineNumber":53,"sourceCode":"\treturn cmd\n}\n\nfunc createManifestList(ctx context.Context, dockerCLI command.Cli, args []string, opts createOpts) error {\n\tnewRef := args[0]\n\ttargetRef, err := normalizeReference(newRef)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error parsing name for manifest list %s: %w\", newRef, err)\n\t}\n\n\tmanifestStore := newManifestStore(dockerCLI)\n\t_, err = manifestStore.GetList(targetRef)\n\tswitch {\n\tcase errdefs.IsNotFound(err):\n\t\t// New manifest list\n\tcase err != nil:\n\t\treturn err\n\tcase !opts.amend:\n\t\treturn errors.New(\"refusing to amend an existing manifest list with no --amend flag\")\n\t}\n\n\t// Now create the local manifest list transaction by looking up the manifest schemas\n\t// for the constituent images:\n\tmanifests := args[1:]\n\tfor _, manifestRef := range manifests {\n\t\tnamedRef, err := normalizeReference(manifestRef)\n\t\tif err != nil {\n\t\t\t// TODO: wrap error?\n\t\t\treturn err\n\t\t}\n\n\t\tmanifest, err := getManifest(ctx, dockerCLI, targetRef, namedRef, opts.insecure)\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif err := manifestStore.Save(targetRef, namedRef, manifest); err != nil {\n\t\t\treturn err","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/manifest/create_list.go#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Add --amend to update the existing list: docker manifest create --amend myrepo/app:tag img1 img2","Or remove the stale local list first: docker manifest rm myrepo/app:tag","Use docker manifest push --purge in scripts so the local list is deleted after a successful push","Consider docker buildx imagetools create, which handles multi-arch manifest creation without local store state"],"exampleFix":"# before\ndocker manifest create myrepo/app:1.0 myrepo/app:1.0-amd64 myrepo/app:1.0-arm64\n# after (list already exists locally)\ndocker manifest create --amend myrepo/app:1.0 myrepo/app:1.0-amd64 myrepo/app:1.0-arm64","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker-cli","manifest","multi-arch","amend","local-state"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}