Troubleshoot plugins changedplugins/troubleshooting
Nearest release: v2.1.286, published 7 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 1 Oct 2026 00:29 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 1 Oct 2026 01:07 UTC.
Upstream edited
Recorded here
Lines+38added
Lines−2removed
From line
193
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits29to this page, all time
#### `Bundled MCP server "<name>" was not started: it needs configuration`
The whole hunk
from line 193, old and new numbered
/
from line 193
193193
194194A successful add prints `Successfully added marketplace: <name>`.
195195
196<h3 id="invalid-git-url">
197 `Invalid git URL`
198</h3>
199
200You added a marketplace, installed a plugin, or ran an update from a git address, and the command failed with `Invalid git URL` in its message.
201
202Claude Code checks every git address before running git. It refuses an address whose protocol it doesn't support. It also refuses an address that git could read as naming a different server or folder than the one the address shows.
203
204The text after the address names what to change. Rewrite the address as the message says and run the command again.
205
206A refusal that instead says `is blocked by enterprise policy` comes from your organization's settings. See [Marketplace source is blocked by enterprise policy](#marketplace-source-is-blocked-by-enterprise-policy).
207
196208<h3 id="path-does-not-exist">
197209 `Path does not exist: <path>`
198210</h3>
from line 412
400412
401413`claude plugin install` in your shell prints a different message. For a plugin already installed at the target scope, it prints `Plugin "<name>@<marketplace>" is already installed (scope: user)` and exits 0. If its cache directory is missing, the same command re-downloads it.
402414
415<h3 id="plugin-would-share-its-folder">
416 `"<plugin>" was not installed: it would share its folder with "<other>"`
417</h3>
418
419You installed a plugin through `claude plugin install`, `/plugin`, or an install suggestion in a session, and Claude Code refused it with this line, or with `would share its saved data with`.
420
421The refused plugin's id and an installed plugin's id map to the same folder on disk: they are the same once `.` and `@` are written as `-`. On macOS and Windows, ids that differ only in capitals map to the same folder too. Installing both would put one plugin's files in the other's folder, so Claude Code refuses and the installed plugin keeps its files.
422
423The message names the way out:
424
425* **The other plugin is installed**: the message says `Only one of the two can be installed.` and names the `claude plugin uninstall` command, or the uninstall step in `/plugin`, that removes the other plugin. Run it, then install again. For what the uninstall removes, see [What an uninstall deletes and keeps](/docs/en/plugins/cli-reference#what-an-uninstall-deletes-and-keeps).
426* **Both ids arrive in one install**, such as a plugin and a dependency it needs: no install order helps. Only a maintainer of the marketplace that lists the two plugins can fix it, by renaming one of them. When the two come from different marketplaces, a maintainer of either one can.
427
403428<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">
404429 `This plugin uses a source type your Claude Code version does not support`
405430</h3>
from line 793
768793* **`URL is unset or invalid`**: a `${user_config.*}` option that the URL uses isn't set. Run `/plugin configure <plugin>` to set it
769794* **`has an invalid MCP url`** or **`headersHelper for MCP server '<server>' references ${user_config.*}`**: the plugin's own configuration is at fault. Fix the `url` or `headersHelper` in your plugin's MCP configuration, or report it to the plugin's author if the plugin isn't yours. The `headersHelper` case has its own entry under [plugin command references user\_config](/docs/en/errors#plugin-command-references-user-config)
770795
796#### `Bundled MCP server "<name>" was not started: it needs configuration`
797
798The plugin includes the server as an [MCPB bundle](/docs/en/plugins/components#include-a-packaged-mcpb-server) that declares `user_config`, and a required setting has no saved value yet or a saved value fails the bundle's own validation, so Claude Code skips starting the server. The rest of the plugin works.
799
800Select the plugin on `/plugin`'s **Installed** tab and choose **Configure** to supply the values. After you save, `/plugin` shows `Configuration saved.` and closes, and Claude Code reloads plugins as described under [Manage installed plugins](/docs/en/plugins/install#manage-installed-plugins). The server starts once that reload applies. Before v2.1.285, Claude Code skipped the server without showing this line.
801
771802#### Server is configured but never connects
772803
773804Run `/mcp` to see the server's status. When the server is healthy, `/mcp` lists it as connected.
from line 931
900931
901932Your plugin declares `userConfig` options, but no configuration dialog appears when you install it.
902933
903The interactive install shows the dialog, and the shell command takes the values as flags instead:
934Whether the install asks for the values depends on where you run it:
904935
905936* **`/plugin install` in a session, or the Discover tab in `/plugin`**: the dialog is part of this interactive install
937* **The VS Code extension's Manage plugins dialog**: asks for unset options as a form after the install. Before v2.1.285, installing there showed no options form, so set the values from a terminal session with `/plugin configure <plugin>@<marketplace>`
906938* **`claude plugin install` in your shell**: never prompts for `userConfig` values. It saves any `--config KEY=VALUE` values you pass, and when options remain unset it prints `N userConfig options not yet set — run /plugin configure <plugin>@<marketplace> in Claude Code, or pass --config KEY=VALUE.` When any of the unset options is required, `(M required)` follows `not yet set`.
907939
908940If you installed from the shell, pass the values with `--config`, one flag per option:
from line 943
911943claude plugin install my-plugin@my-marketplace --config api_url=https://example.com
912944```
913945
914When every option is set, the install output carries no `not yet set` line. To open the dialog afterwards instead, run `/plugin configure my-plugin@my-marketplace` in a session.
946When every option is set, the install output carries no `not yet set` line.
915947
948To open the dialog afterwards instead, run `/plugin configure my-plugin@my-marketplace` in a session. From the shell, [`claude plugin configure`](/docs/en/plugins/cli-reference#plugin-configure) shows which options are still unset and saves values piped in on stdin. It requires Claude Code v2.1.285 or later.
949
916950If you pass a `--config` key the manifest doesn't declare, the plugin still installs, and the command prints `⚠ Installed, but --config not applied: --config key "<key>" isn't declared in this plugin's userConfig.` followed by the keys the plugin does declare.
951
952For a plugin that ships an [MCPB bundle file](/docs/en/plugins/components#include-a-packaged-mcpb-server) declaring `user_config` of its own, the message reads `isn't declared in this plugin's userConfig or by its bundled MCP servers.` instead, and the known keys include that server's keys, written `<server>.<key>`. A bundle the manifest references by URL isn't read at install time, so its keys aren't listed and the message says to configure it in `/plugin`. Setting `<server>.<key>` keys requires Claude Code v2.1.285 or later.
917953
918954<h3 id="claude-plugin-validate-reports-errors">
919955 `claude plugin validate` reports errors
No line in this hunk matches that.