claude-code - 💡(How to fix) Fix [DOCS] Plugin marketplace docs missing unrecognized source format behavior [1 comments, 2 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugin-marketplaces#plugin-sources

Section/Topic

Plugin sources, marketplace validation/troubleshooting, and plugin installation failure behavior for plugin entries that use an unrecognized source.source format.

Current Documentation

The marketplace guide documents the currently supported plugin source types:

Plugin sources tell Claude Code where to fetch each individual plugin listed in your marketplace. These are set in the source field of each plugin entry in marketplace.json.

| Source | Type | Fields | Notes | | Relative path | string (e.g. "./my-plugin") | none | Local directory within the marketplace repo. Must start with ./. Resolved relative to the marketplace root, not the .claude-plugin/ directory | | github | object | repo, ref?, sha? | | | url | object | url, ref?, sha? | Git URL source | | git-subdir | object | url, path, ref?, sha? | Subdirectory within a git repo. Clones sparsely to minimize bandwidth for monorepos | | npm | object | package, version?, registry? | Installed via npm install |

The troubleshooting section covers generic marketplace and install failures:

Marketplace not loading

Symptoms: Can't add marketplace or see plugins from it

Solutions:

• Verify the marketplace URL is accessible
• Check that .claude-plugin/marketplace.json exists at the specified path
• Ensure JSON syntax is valid and frontmatter is well-formed using claude plugin validate or /plugin validate
• For private repositories, confirm you have access permissions

And:

Plugin installation failures

Symptoms: Marketplace appears but plugin installation fails

Solutions:

• Verify plugin source URLs are accessible
• Check that plugin directories contain required files
• For GitHub sources, ensure repositories are public or you have access
• Test plugin sources manually by cloning/downloading

What's Wrong or Missing?

Changelog v2.1.120 says Claude Code fixed /plugin marketplace loading when one marketplace entry uses an unrecognized source format: the marketplace entry is now shown, and attempting to install that plugin prompts the user to update.

The current docs list supported source formats, but they do not explain what happens when a marketplace contains a newer or otherwise unrecognized source format. That leaves two user groups without guidance:

A. Marketplace users cannot tell that a marketplace may still load even when one plugin entry cannot be installed by their current Claude Code version.

B. Marketplace authors cannot tell that an unrecognized source format should degrade at install time for that entry instead of making the whole marketplace unavailable.

The existing troubleshooting advice points users toward URL accessibility, JSON syntax, repository access, or manual cloning. Those checks do not fit the v2.1.120 compatibility case, where the catalog can be valid and accessible but one entry requires a newer Claude Code version that understands its source format.

Suggested Improvement

Add a short compatibility note under Plugin sources or Troubleshooting that explains unsupported source formats.

Suggested wording:

Unsupported source formats: If a marketplace contains a plugin entry whose source.source value is not recognized by your installed Claude Code version, the marketplace can still load and display the entry. Installing that plugin fails with guidance to update Claude Code. Update Claude Code, refresh the marketplace, then retry the install.

Also update the Plugin installation failures troubleshooting list with a bullet such as:

• If the error says the plugin uses an unrecognized source format, update Claude Code and run /plugin marketplace update <marketplace-name> before retrying the install.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 5 page sections affected across 2 pages.

Source: Changelog v2.1.120: Fixed /plugin marketplace failing to load when one entry uses an unrecognized source format — that entry is shown but installing it prompts you to update