docker/cli · error

invalid name

Error message

invalid name: %s

What it means

Returned by runInstall (plugin/install.go:87) when the --alias value parses as a reference.Canonical reference, i.e. it contains a digest (`@sha256:...`). Plugin local names must not be digest-pinned, so after reference.ParseNormalizedNamed succeeds the code checks the Canonical interface and rejects it. A non-digest name that fails to parse returns the parser's own error instead.

Solutions

1. Use a plain name (optionally with a tag) for --alias, e.g. `myplugin:latest`.
2. If you need a digest, install by digest on the remote side, not the alias.
3. Omit --alias entirely to let the plugin install under its remote name.

Example fix

// before
docker plugin install --alias myplugin@sha256:abc123 origin:latest
// after
docker plugin install --alias myplugin origin:latest

// Reject digest-style aliases up front.
func validateAlias(alias string) error {
    ref, err := reference.ParseNormalizedNamed(alias)
    if err != nil { return err }
    if _, ok := ref.(reference.Canonical); ok {
        return fmt.Errorf("alias must not contain a digest: %s", alias)
    }
    return nil
}

// isTaggableAlias reports whether alias is a non-digest named reference.
func isTaggableAlias(alias string) bool {
    ref, err := reference.ParseNormalizedNamed(alias)
    if err != nil { return false }
    _, ok := ref.(reference.Canonical)
    return !ok
}

When it happens

Trigger: Running `docker plugin install --alias myplugin@sha256:abcd1234... origin:tag`. The alias is meant to be a friendly local tag, not a content-addressed digest.

Common situations: Confusing the plugin alias with an image digest, pasting a full digest reference as the alias, or scripting that concatenates `name@digest`.

Related errors

• invalid name
• error parsing remote upgrade image reference
• error parsing current image reference
• annotate: error parsing name for manifest list
• annotate: error parsing name for manifest

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

Appendix: source

Thrown at cli/command/plugin/install.go:87

		RegistryAuth:          encodedAuth,
		RemoteRef:             ref.String(),
		Disabled:              opts.disable,
		AcceptAllPermissions:  opts.grantPerms,
		AcceptPermissionsFunc: acceptPrivileges(dockerCLI, opts.remote),
		PrivilegeFunc:         nil,
		Args:                  opts.args,
	}, nil
}

func runInstall(ctx context.Context, dockerCLI command.Cli, opts pluginOptions) error {
	var localName string
	if opts.localName != "" {
		aref, err := reference.ParseNormalizedNamed(opts.localName)
		if err != nil {
			return err
		}
		if _, ok := aref.(reference.Canonical); ok {
			return fmt.Errorf("invalid name: %s", opts.localName)
		}
		localName = reference.FamiliarString(reference.TagNameOnly(aref))
	}

	options, err := buildPullConfig(dockerCLI, opts)
	if err != nil {
		return err
	}
	responseBody, err := dockerCLI.Client().PluginInstall(ctx, localName, options)
	if err != nil {
		return err
	}
	defer func() {
		_ = responseBody.Close()
	}()
	if err := jsonstream.Display(ctx, responseBody, dockerCLI.Out()); err != nil {
		return err
	}

View on GitHub (pinned to 4f84911bfe)