docker/cli · error

the plugin must be disabled before upgrading

Error message

the plugin must be disabled before upgrading

What it means

Raised by `docker plugin upgrade` when PluginInspect shows the plugin is currently enabled. Upgrading replaces the plugin's rootfs and configuration in place, which cannot be done safely while the plugin is running, so the CLI requires it be disabled first.

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 e9452d6e78)

Solutions

1. Disable first: `docker plugin disable <name>`, then `docker plugin upgrade <name>`, then `docker plugin enable <name>`
2. If disable fails because the plugin is in use, stop/remove containers or volumes using it (or use `docker plugin disable -f` understanding the risk)
3. Script the disable → upgrade → enable sequence for maintenance windows

Example fix

# before
docker plugin upgrade vieux/sshfs
# after
docker plugin disable vieux/sshfs
docker plugin upgrade vieux/sshfs
docker plugin enable vieux/sshfs

When it happens

Trigger: `docker plugin upgrade <name> [remote]` on a plugin whose Enabled field is true — typically any actively-used volume/network/log driver plugin.

Common situations: Upgrading a storage or network driver plugin that containers currently depend on; automation that upgrades plugins without a disable step; forgetting the plugin auto-enabled on install.

Related errors

• plugin upgrade has been cancelled
• context must be a directory
• container ID file found, make sure the other container isn't
• every ip-range or gateway must have a corresponding subnet
• multiple overlapping subnet configuration is not supported

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