{"id":"86257c3ac958ed6a","repo":"docker/cli","slug":"the-plugin-must-be-disabled-before-upgrading","errorCode":null,"errorMessage":"the plugin must be disabled before upgrading","messagePattern":"the plugin must be disabled before upgrading","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/plugin/upgrade.go","lineNumber":51,"sourceCode":"\t}\n\n\tflags := cmd.Flags()\n\tflags.BoolVar(&options.grantPerms, \"grant-all-permissions\", false, \"Grant all permissions necessary to run the plugin\")\n\t// TODO(thaJeztah): DEPRECATED: remove in v29.1 or v30\n\tflags.Bool(\"disable-content-trust\", true, \"Skip image verification (deprecated)\")\n\t_ = flags.MarkDeprecated(\"disable-content-trust\", \"support for docker content trust was removed\")\n\tflags.BoolVar(&options.skipRemoteCheck, \"skip-remote-check\", false, \"Do not check if specified remote plugin matches existing plugin image\")\n\treturn cmd\n}\n\nfunc runUpgrade(ctx context.Context, dockerCLI command.Cli, opts pluginOptions) error {\n\tres, err := dockerCLI.Client().PluginInspect(ctx, opts.localName, client.PluginInspectOptions{})\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error reading plugin data: %w\", err)\n\t}\n\n\tif res.Plugin.Enabled {\n\t\treturn errors.New(\"the plugin must be disabled before upgrading\")\n\t}\n\n\topts.localName = res.Plugin.Name\n\tif opts.remote == \"\" {\n\t\topts.remote = res.Plugin.PluginReference\n\t}\n\tremote, err := reference.ParseNormalizedNamed(opts.remote)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error parsing remote upgrade image reference: %w\", err)\n\t}\n\tremote = reference.TagNameOnly(remote)\n\n\told, err := reference.ParseNormalizedNamed(res.Plugin.PluginReference)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"error parsing current image reference: %w\", err)\n\t}\n\told = reference.TagNameOnly(old)\n","sourceCodeStart":33,"sourceCodeEnd":69,"githubUrl":"https://github.com/docker/cli/blob/e9452d6e785f6e365712b9d71bd7517591773c86/cli/command/plugin/upgrade.go#L33-L69","documentation":"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.","triggerScenarios":"`docker plugin upgrade <name> [remote]` on a plugin whose Enabled field is true — typically any actively-used volume/network/log driver plugin.","commonSituations":"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.","solutions":["Disable first: `docker plugin disable <name>`, then `docker plugin upgrade <name>`, then `docker plugin enable <name>`","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)","Script the disable → upgrade → enable sequence for maintenance windows"],"exampleFix":"# before\ndocker plugin upgrade vieux/sshfs\n# after\ndocker plugin disable vieux/sshfs\ndocker plugin upgrade vieux/sshfs\ndocker plugin enable vieux/sshfs","handlingStrategy":null,"validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":["docker","plugin","upgrade","lifecycle"],"analyzedSha":"e9452d6e785f6e365712b9d71bd7517591773c86","analyzedAt":"2026-08-01T07:09:22.474Z","schemaVersion":2}