claude-code - 💡(How to fix) Fix [DOCS] Plugin auto-update docs omit version-constraint skip diagnostics [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/discover-plugins

Section/Topic

Configure auto-updates, the /plugin Errors tab description, and related /doctor troubleshooting guidance for plugin update failures

Current Documentation

The docs currently say:

Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions. If any plugins were updated, you'll see a notification prompting you to run /reload-plugins.

Run /plugin to open the plugin manager. This opens a tabbed interface with four tabs you can cycle through using Tab (or Shift+Tab to go backward):

• Discover: browse available plugins from all your marketplaces
• Installed: view and manage your installed plugins
• Marketplaces: add, remove, or update your added marketplaces
• Errors: view any plugin loading errors

Run /doctor to diagnose issues. It checks:

• Installation type, version, and search functionality
• Auto-update status and available versions
• Invalid settings files (malformed JSON, incorrect types)
• MCP server configuration errors
• Keybinding configuration problems
• Context usage warnings (large CLAUDE.md files, high MCP token usage, unreachable permission rules)
• Plugin and agent loading errors

Plugin versions determine cache paths and update detection.

| version | string | Optional. Version or version range (for example, 2.1.0, ^2.0.0, ~1.5.0) |

What's Wrong or Missing?

The docs explain plugin auto-updates, the /plugin Errors tab, and /doctor in general terms, but they do not document a new user-visible failure mode added in changelog v2.1.118: a plugin auto-update can be skipped because another installed plugin's version constraint blocks it.

The docs also do not tell users where that skip reason now appears: /doctor and the /plugin Errors tab.

Without that guidance, users can see a plugin remain on an older version and have no documented explanation that the update was intentionally skipped due to a conflicting version constraint, or where to look for the diagnostic.

Suggested Improvement

Add a short troubleshooting note to the plugin docs that covers this specific update outcome:

1. In discover-plugins, extend Configure auto-updates to note that auto-update may skip a plugin when another installed plugin has a conflicting version constraint.
2. Explicitly tell users to check /doctor and the /plugin Errors tab for the skip reason.
3. In plugin-marketplaces or troubleshooting docs, add a brief explanation that plugin version ranges can prevent an update from being applied when installed plugins are constrained incompatibly.

Suggested wording:

If Claude Code skips a plugin auto-update because another installed plugin's version constraint would be violated, the reason appears in /doctor and in the /plugin Errors tab. Review installed plugin version ranges or pinned versions to resolve the conflict.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.118

Exact changelog entry: When auto-update skips a plugin due to another plugin's version constraint, the skip now appears in /doctor and the /plugin Errors tab