What causes "%s not found" in docker/cli?

Create the list first: `docker manifest create `.

not found

Error message

%s not found

What it means

Returned by `runPush` (push.go:71-77) when `GetList(targetRef)` succeeds but returns an empty slice. This means no manifest list with that name exists in the local store, so there is nothing to push. Distinct from a NotFound error from the store itself.

Solutions

Create the list first: `docker manifest create <name> <images...>`.
Verify the name matches what was created (check for typos/tag differences).
Re-create after a --purge push if you need to push again.
Inspect local manifests to confirm presence before pushing.

Example fix

# before
docker manifest push mylist:v2     # never created
# after
docker manifest create mylist:v2 img1 img2
docker manifest push mylist:v2

Defensive patterns

Strategy: validation

Validate before calling

store := newManifestStore(cli)
list, err := store.GetList(targetRef)
if err != nil || len(list) == 0 {
    return fmt.Errorf("no local manifest list %s; run `docker manifest create` first", targetRef)
}

Try / catch

if err := runPush(ctx, cli, opts); err != nil {
    if strings.HasSuffix(err.Error(), " not found") {
        return fmt.Errorf("%w — create the list before pushing", err)
    }
    return err
}

Prevention

Always create the list before push.
Avoid push --purge until you're sure you won't re-push.
Verify the list name spelling.

When it happens

Trigger: Running `docker manifest push typo-name` where the list was never created locally, or was already purged by a previous `push --purge`.

Common situations: Forgetting to run `docker manifest create` first, typo in the list name, or a prior push with --purge that removed it.

Related errors

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

Appendix: source

Thrown at cli/command/manifest/push.go:76

	flags := cmd.Flags()
	flags.BoolVarP(&opts.purge, "purge", "p", false, "Remove the local manifest list after push")
	flags.BoolVar(&opts.insecure, "insecure", false, "Allow push to an insecure registry")
	return cmd
}

func runPush(ctx context.Context, dockerCli command.Cli, opts pushOpts) error {
	targetRef, err := normalizeReference(opts.target)
	if err != nil {
		return err
	}

	manifests, err := newManifestStore(dockerCli).GetList(targetRef)
	if err != nil {
		return err
	}
	if len(manifests) == 0 {
		return fmt.Errorf("%s not found", targetRef)
	}

	req, err := buildPushRequest(manifests, targetRef, opts.insecure)
	if err != nil {
		return err
	}

	if err := pushList(ctx, dockerCli, req); err != nil {
		return err
	}
	if opts.purge {
		return newManifestStore(dockerCli).Remove(targetRef)
	}
	return nil
}

func buildPushRequest(manifests []types.ImageManifest, targetRef reference.Named, insecure bool) (pushRequest, error) {
	req := pushRequest{targetRef: targetRef, insecure: insecure}

View on GitHub (pinned to 4f84911bfe)