docker/cli · error

tag can't be used with --all-tags/-a

Error message

tag can't be used with --all-tags/-a

What it means

runPull() validates the reference against --all-tags semantics: -a pulls every tag in a repository, which only makes sense for a name-only reference (IsNameOnly). If the user gave a specific tag (or digest) AND -a, the combination is contradictory and rejected before contacting the registry.

Solutions

1. Drop the tag to pull all tags: `docker pull -a myimage`
2. Drop -a to pull a single tag: `docker pull myimage:latest`
3. Pick one intent (all tags vs one tag) and align the flags

Example fix

// before
docker pull -a myimage:latest
// after
docker pull -a myimage

ref, err := reference.ParseNormalizedNamed(opts.remote)
if err != nil { return err }
if opts.all && !reference.IsNameOnly(ref) {
    return errors.New("--all-tags requires a name-only reference without tag/digest")
}

func isNameOnlyRef(s string) bool {
    ref, err := reference.ParseNormalizedNamed(s)
    if err != nil { return false }
    return reference.IsNameOnly(ref)
}

When it happens

Trigger: `docker pull -a myimage:latest` or `docker pull --all-tags myimage@sha256:...`.

Common situations: Combining -a with an explicit tag/digest by habit; copy-pasting a tagged reference into an all-tags command.

Related errors

• tag can't be used with --all-tags/-a
• refusing to amend an existing manifest list with no --amend…
• unrecognized config key
• --quiet is not yet supported with --tree
• --no-trunc is not yet supported with --tree

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

Appendix: source

Thrown at cli/command/image/pull.go:75

	// TODO(thaJeztah): DEPRECATED: remove in v29.1 or v30
	flags.Bool("disable-content-trust", true, "Skip image verification (deprecated)")
	_ = flags.MarkDeprecated("disable-content-trust", "support for docker content trust was removed")

	flags.StringVar(&opts.platform, "platform", os.Getenv("DOCKER_DEFAULT_PLATFORM"), "Set platform if server is multi-platform capable")
	_ = flags.SetAnnotation("platform", "version", []string{"1.32"})
	_ = cmd.RegisterFlagCompletionFunc("platform", completion.Platforms())

	return cmd
}

// runPull performs a pull against the engine based on the specified options
func runPull(ctx context.Context, dockerCLI command.Cli, opts pullOptions) error {
	distributionRef, err := reference.ParseNormalizedNamed(opts.remote)
	switch {
	case err != nil:
		return err
	case opts.all && !reference.IsNameOnly(distributionRef):
		return errors.New("tag can't be used with --all-tags/-a")
	case !opts.all && reference.IsNameOnly(distributionRef):
		distributionRef = reference.TagNameOnly(distributionRef)
		if tagged, ok := distributionRef.(reference.Tagged); ok && !opts.quiet {
			_, _ = fmt.Fprintln(dockerCLI.Out(), "Using default tag:", tagged.Tag())
		}
	}

	var ociPlatforms []ocispec.Platform
	if opts.platform != "" {
		// TODO(thaJeztah): add a platform option-type / flag-type.
		p, err := platforms.Parse(opts.platform)
		if err != nil {
			return err
		}
		ociPlatforms = append(ociPlatforms, p)
	}

	encodedAuth, err := command.RetrieveAuthTokenFromImage(dockerCLI.ConfigFile(), distributionRef.String())

View on GitHub (pinned to 4f84911bfe)