docker/cli · info · cancelledErr

plugin upgrade has been cancelled

Error message

plugin upgrade has been cancelled

What it means

Returned by `docker plugin upgrade` when the new remote image reference does not match the plugin's current reference and the user answers no to the 'Plugin images do not match, are you sure?' prompt. Wrapped in cancelledErr so it is recognized as a deliberate abort; nothing is pulled or changed.

Source

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

	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
	}

	responseBody, err := dockerCLI.Client().PluginUpgrade(ctx, opts.localName, client.PluginUpgradeOptions(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 e9452d6e78)

Solutions

1. Answer 'y' at the prompt if the different image is intentional
2. Pass --skip-remote-check to bypass the reference-match confirmation in scripts
3. Use a remote that matches the installed plugin's reference (check `docker plugin inspect --format '{{.PluginReference}}' <name>`) if the mismatch was accidental

Example fix

# before
docker plugin upgrade myplugin registry2.example.com/myplugin:v2
# after (intentional cross-repo upgrade in automation)
docker plugin upgrade --skip-remote-check myplugin registry2.example.com/myplugin:v2

When it happens

Trigger: `docker plugin upgrade <name> <different-remote>` without --skip-remote-check, where the normalized/tagged remote differs from the installed plugin's PluginReference, and the confirmation prompt is declined.

Common situations: Switching a plugin to a different repository, tag, or registry mirror; automation upgrading to a retagged image and failing on the interactive prompt in a non-TTY environment.

Related errors

• the plugin must be disabled before upgrading
• network prune has been cancelled
• context must be a directory
• builder prune has been cancelled
• container prune has been cancelled

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