docker/cli · error

error parsing current image reference

Error message

error parsing current image reference: %w

What it means

Returned by runUpgrade (plugin/upgrade.go:66) wrapping the error from reference.ParseNormalizedNamed on the EXISTING plugin's stored PluginReference. Unlike [369] this is not user-supplied input; it is the reference persisted in the local plugin's metadata. A parse failure here indicates the plugin's stored reference is malformed or in an unexpected form.

Solutions

1. Upgrade the Docker CLI/daemon to a matching version that understands the stored reference.
2. Remove and reinstall the plugin from a known-good reference (`docker plugin rm` then `docker plugin install`).
3. Use `--skip-remote-check` only if the remote differs and you can supply a fresh remote; otherwise reinstall.

Example fix

// before: plugin has unparseable stored PluginReference
docker plugin upgrade oldplugin
// after
docker plugin rm -f oldplugin
docker plugin install oldplugin registry.example.com/oldplugin:latest

// On unparseable stored reference, fall back to reinstall from a known-good ref.
err := runUpgrade(ctx, cli, opts)
if err != nil && strings.Contains(err.Error(), "error parsing current image reference") {
    _ = cli.Client().PluginRemove(ctx, name, types.PluginRemoveOptions{Force: true})
    return runInstall(ctx, cli, pluginOptions{remote: knownGoodRef})
}

When it happens

Trigger: A locally installed plugin whose PluginReference cannot be parsed by the current reference library — e.g. installed by an older Docker version using a now-invalid format, or a reference with an unusual scheme. Triggered on any `docker plugin upgrade` of such a plugin when the remote is parsed successfully first.

Common situations: Version skew between the CLI and the daemon/plugin metadata, plugins installed long ago with legacy reference formats, or a manually corrupted plugin config.

Related errors

• error parsing remote upgrade image reference
• invalid name
• invalid name
• error reading plugin data
• the plugin must be disabled before upgrading

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

Appendix: source

Thrown at cli/command/plugin/upgrade.go:66

	}

	if res.Plugin.Enabled {
		return errors.New("the plugin must be disabled before upgrading")
	}

	opts.localName = res.Plugin.Name
	if opts.remote == "" {
		opts.remote = res.Plugin.PluginReference
	}
	remote, err := reference.ParseNormalizedNamed(opts.remote)
	if err != nil {
		return fmt.Errorf("error parsing remote upgrade image reference: %w", err)
	}
	remote = reference.TagNameOnly(remote)

	old, err := reference.ParseNormalizedNamed(res.Plugin.PluginReference)
	if err != nil {
		return fmt.Errorf("error parsing current image reference: %w", err)
	}
	old = reference.TagNameOnly(old)

	_, _ = fmt.Fprintf(dockerCLI.Out(), "Upgrading plugin %s from %s to %s\n", res.Plugin.Name, reference.FamiliarString(old), reference.FamiliarString(remote))
	if !opts.skipRemoteCheck && remote.String() != old.String() {
		r, err := prompt.Confirm(ctx, dockerCLI.In(), dockerCLI.Out(), "Plugin images do not match, are you sure?")
		if err != nil {
			return err
		}
		if !r {
			return cancelledErr{errors.New("plugin upgrade has been cancelled")}
		}
	}

	options, err := buildPullConfig(dockerCLI, opts)
	if err != nil {
		return err
	}

View on GitHub (pinned to 4f84911bfe)