docker/cli · error

error reading plugin data

Error message

error reading plugin data: %w

What it means

Returned by runUpgrade (plugin/upgrade.go:47) wrapping the error from PluginInspect. Before upgrading, the CLI inspects the local plugin to read its name and current PluginReference; any failure (plugin missing, daemon unreachable, permission denied) is surfaced with this wrapper so the %w chain preserves the root cause.

Solutions

1. Verify the plugin exists: `docker plugin ls` and use the exact name.
2. Ensure the Docker daemon is running and reachable (`docker info`).
3. Check socket/permissions if you get a connection or forbidden error in the wrapped cause.
4. Install the plugin first with `docker plugin install` if it is not present.

Example fix

// before
docker plugin upgrade typo-name
// after
docker plugin ls   # confirm exact name
docker plugin upgrade real-name new-ref:latest

// Confirm the plugin exists before attempting an upgrade.
func pluginExists(ctx context.Context, c client.PluginAPIClient, name string) error {
    if _, err := c.PluginInspectWithRaw(ctx, name); err != nil {
        return fmt.Errorf("plugin %s not inspectable: %w", name, err)
    }
    return nil
}

// Wrap upgrade attempts and report inspect failures distinctly.
err := runUpgrade(ctx, cli, opts)
if err != nil {
    if strings.Contains(err.Error(), "error reading plugin data") {
        // plugin missing or daemon unreachable; guide user accordingly
    }
    return err
}

When it happens

Trigger: Running `docker plugin upgrade` against a plugin name that does not exist locally, when the daemon is not running, or when the API call is denied. Also if the local plugin name is misspelled.

Common situations: Upgrading a plugin that was removed, typo in the plugin name, daemon down or socket permission issues, or running upgrade against a remote-only reference with no local install.

Related errors

• error parsing remote upgrade image reference
• error parsing current image reference
• the plugin must be disabled before upgrading
• plugin upgrade has been cancelled
• template parsing error

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

Appendix: source

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

		},
		Annotations:           map[string]string{"version": "1.26"},
		ValidArgsFunction:     completeNames(dockerCLI, stateAny), // TODO(thaJeztah): should only complete for the first arg
		DisableFlagsInUseLine: true,
	}

	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 {

View on GitHub (pinned to 4f84911bfe)