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

docker pull --all-tags/-a pulls every tag of a repository, so the image reference must be a bare repository name. In runPull (cli/command/image/pull.go:74-75), after ParseNormalizedNamed, if opts.all is set and reference.IsNameOnly() is false — the reference carries a :tag or @digest — the two instructions conflict and the CLI rejects the command rather than guess which one you meant.

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 e9452d6e78)

Solutions

1. Drop the tag/digest when using --all-tags: docker pull -a ubuntu
2. Or drop --all-tags and pull the single tag: docker pull ubuntu:22.04
3. In scripts, make the tag and the --all-tags flag mutually exclusive when building the command line

Example fix

# before
docker pull --all-tags ubuntu:22.04
# after
docker pull --all-tags ubuntu

When it happens

Trigger: `docker pull -a ubuntu:22.04` or `docker pull --all-tags myrepo/app@sha256:...` — any --all-tags pull whose reference includes a tag or digest. Note the implicit ':latest' is only appended when -a is NOT set, so only an explicitly written tag/digest triggers this.

Common situations: Adding -a to an existing pull command that already has a tag; scripts that template IMAGE:TAG and conditionally append --all-tags; confusion thinking -a plus a tag means 'this tag and newer'.

Related errors

• tag can't be used with --all-tags/-a
• conflicting options: cannot specify both --network-alias and
• conflicting options: cannot specify both --link and per-netw
• conflicting options: cannot specify both --ip and per-networ
• conflicting options: cannot specify both --ip6 and per-netwo

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