docker/cli · error

invalid name

Error message

invalid name: %s

What it means

Returned by runPush (plugin/push.go:41) when the plugin argument parses as a reference.Canonical (digest) reference. Plugin push targets a tagged plugin image in a registry; pushing by digest is not a meaningful operation, so after ParseNormalizedNamed the code checks the Canonical type and rejects it.

Solutions

1. Push by name and tag, e.g. `docker plugin push myplugin:latest`.
2. Tag the plugin first if it only has a digest reference.
3. Use `docker plugin inspect` to find the tagged PluginReference to push.

Example fix

// before
docker plugin push myplugin@sha256:abc123
// after
docker plugin push myplugin:latest

// Ensure the push target is a tag, not a digest.
func validatePushTarget(name string) error {
    ref, err := reference.ParseNormalizedNamed(name)
    if err != nil { return err }
    if _, ok := ref.(reference.Canonical); ok {
        return fmt.Errorf("cannot push by digest: %s", name)
    }
    return nil
}

// isPushableName reports whether name is a tag (non-canonical) reference.
func isPushableName(name string) bool {
    ref, err := reference.ParseNormalizedNamed(name)
    if err != nil { return false }
    _, ok := ref.(reference.Canonical)
    return !ok
}

When it happens

Trigger: Running `docker plugin push myplugin@sha256:abcd1234...`. The push command needs a name:tag, not a digest.

Common situations: Copy-pasting a digest from `docker plugin inspect` instead of the tag, or assuming push works like pull-by-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/459f64a85c400318. Report an issue: GitHub.

Appendix: source

Thrown at cli/command/plugin/push.go:41

		},
		ValidArgsFunction:     completeNames(dockerCLI, stateAny),
		DisableFlagsInUseLine: true,
	}

	flags := cmd.Flags()
	// 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")
	return cmd
}

func runPush(ctx context.Context, dockerCli command.Cli, name string) error {
	named, err := reference.ParseNormalizedNamed(name)
	if err != nil {
		return err
	}
	if _, ok := named.(reference.Canonical); ok {
		return fmt.Errorf("invalid name: %s", name)
	}

	named = reference.TagNameOnly(named)
	encodedAuth, err := command.RetrieveAuthTokenFromImage(dockerCli.ConfigFile(), named.String())
	if err != nil {
		return err
	}

	responseBody, err := dockerCli.Client().PluginPush(ctx, reference.FamiliarString(named), client.PluginPushOptions{
		RegistryAuth: encodedAuth,
	})
	if err != nil {
		return err
	}
	defer func() {
		_ = responseBody.Close()
	}()
	return jsonstream.Display(ctx, responseBody, dockerCli.Out())

View on GitHub (pinned to 4f84911bfe)