docker/cli · error

the plugin must be disabled before upgrading

Error message

the plugin must be disabled before upgrading

What it means

Thrown by runUpgrade after PluginInspect when res.Plugin.Enabled is true. Docker does not allow upgrading a plugin that is currently enabled/running because the upgrade process replaces the plugin rootfs and configuration in place.

Solutions

1. Disable the plugin first: 'docker plugin disable <name>'.
2. Then run 'docker plugin upgrade <name>'.
3. Re-enable after upgrade: 'docker plugin enable <name>'.

Example fix

# before
docker plugin upgrade myplugin
# after
docker plugin disable myplugin && docker plugin upgrade myplugin && docker plugin enable myplugin

// Inspect and ensure the plugin is disabled before upgrading
res, err := apiClient.PluginInspect(ctx, name, client.PluginInspectOptions{})
if err != nil { return err }
if res.Plugin.Enabled {
    if err := apiClient.PluginDisable(ctx, name, client.PluginDisableOptions{}); err != nil { return err }
}

When it happens

Trigger: Running 'docker plugin upgrade' on a plugin whose enabled state is true (lines 50-52 of upgrade.go).

Common situations: Forgetting to disable a plugin before upgrading; plugins that auto-enable on install; scripting an upgrade without the disable step.

Related errors

• plugin upgrade has been cancelled
• context must be a directory
• every ip-range or gateway must have a corresponding subnet
• multiple overlapping subnet configuration is not supported
• network prune has been cancelled

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

Appendix: source

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

	}

	flags := cmd.Flags()
	flags.BoolVar(&options.grantPerms, "grant-all-permissions", false, "Grant all permissions necessary to run the plugin")
	// 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.BoolVar(&options.skipRemoteCheck, "skip-remote-check", false, "Do not check if specified remote plugin matches existing plugin image")
	return cmd
}

func runUpgrade(ctx context.Context, dockerCLI command.Cli, opts pluginOptions) error {
	res, err := dockerCLI.Client().PluginInspect(ctx, opts.localName, client.PluginInspectOptions{})
	if err != nil {
		return fmt.Errorf("error reading plugin data: %w", err)
	}

	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)

View on GitHub (pinned to 4f84911bfe)