{"record":{"id":"433847cb71125d69","repo":"docker/cli","slug":"error-parsing-remote-upgrade-image-reference-w","errorCode":null,"errorMessage":"error parsing remote upgrade image reference: %w","messagePattern":"error parsing remote upgrade image reference: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/command/plugin/upgrade.go","lineNumber":60,"sourceCode":"}\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\n\t_, _ = fmt.Fprintf(dockerCLI.Out(), \"Upgrading plugin %s from %s to %s\\n\", res.Plugin.Name, reference.FamiliarString(old), reference.FamiliarString(remote))\n\tif !opts.skipRemoteCheck && remote.String() != old.String() {\n\t\tr, err := prompt.Confirm(ctx, dockerCLI.In(), dockerCLI.Out(), \"Plugin images do not match, are you sure?\")\n\t\tif err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif !r {\n\t\t\treturn cancelledErr{errors.New(\"plugin upgrade has been cancelled\")}\n\t\t}","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/docker/cli/blob/4f84911bfe8811e9b028e4b1fee8e7510be79387/cli/command/plugin/upgrade.go#L42-L78","documentation":"Returned by runUpgrade (plugin/upgrade.go:60) wrapping the error from reference.ParseNormalizedNamed on the remote upgrade target. The remote ref (explicit arg or the plugin's stored PluginReference) must be a valid distribution reference; if parsing fails the upgrade aborts before contacting the registry.","triggerScenarios":"Running `docker plugin upgrade PLUGIN <remote>` where <remote> is not a valid image reference: contains illegal characters, uppercase in the wrong place, spaces, or invalid syntax. Example: `docker plugin upgrade myplugin 'bad name!'`.","commonSituations":"Typo in the tag, missing registry prefix, illegal characters in the name, or passing a local path instead of a reference.","solutions":["Supply a valid name[:tag][@digest] reference for the remote.","Omit the remote argument to reuse the plugin's original PluginReference.","Validate the string with reference.ParseNormalizedNamed before invoking."],"exampleFix":"// before\ndocker plugin upgrade myplugin 'bad name!'\n// after\ndocker plugin upgrade myplugin myrepo/myplugin:latest","handlingStrategy":"validation","validationCode":"// Validate the remote reference before upgrading.\nfunc validateRemoteRef(remote string) error {\n    if _, err := reference.ParseNormalizedNamed(remote); err != nil {\n        return fmt.Errorf(\"invalid remote upgrade reference %q: %w\", remote, err)\n    }\n    return nil\n}","typeGuard":"// isValidRemoteRef reports whether remote parses as a normalized named reference.\nfunc isValidRemoteRef(remote string) bool {\n    _, err := reference.ParseNormalizedNamed(remote)\n    return err == nil\n}","tryCatchPattern":null,"preventionTips":["Use standard name[:tag][@digest] syntax for the remote.","Omit the remote arg to reuse the original PluginReference.","Parse references with the distribution/reference library in tooling."],"tags":["plugin","upgrade","reference","docker-cli"],"backgroundTag":null,"analyzedSha":"4f84911bfe8811e9b028e4b1fee8e7510be79387","analyzedAt":"2026-08-07T12:15:29.814Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}