Troubleshoot plugins changedplugins/troubleshooting
Nearest release: v2.1.305, published an hour after 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 20 Oct 2026 18:23 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 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+192added
Lines−304removed
From line
8
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits27to this page, all time
### `/plugin isn't available in this environment` ### `zsh: no such file or directory: /plugin` ### `The term '/plugin' is not recognized as the name of a cmdlet` ### `claude: command not found` after `claude plugin ...` ### `Unknown command` and command spellings that don't exist ### `Marketplace "claude-plugins-official" not found` ### `Marketplace "<name>" not found` ### `Invalid marketplace source format` ### `'<source>' is not a valid GitHub owner/repo shorthand` ### `Invalid git URL` ### `Path does not exist: <path>` ### `Marketplace file not found at <path>/.claude-plugin/marketplace.json` ### `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name` ### `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it` ### `SSH authentication failed` or `HTTPS authentication failed` ### `SSH host key is not in your known_hosts file` ### `Command 'git' not found or is in an unsafe location` ### `Git clone timed out after 120s` ### Marketplace updates keep failing offline ### Marketplace add fails on a GitHub Enterprise Server host ### `Plugin "<name>" not found in marketplace "<marketplace>"` #### `not found in marketplace` with a refresh hint #### `not found in marketplace` with no hint ### `Plugin "<name>" not found in any marketplace` ### `Plugin '<name>@<marketplace>' is already installed globally` ### `"<plugin>" was not installed: it would share its folder with "<other>"` ### `This plugin uses a source type your Claude Code version does not support` ### `Plugin archive integrity check failed` ### `An npm plugin source must name a registry package` ### `Marketplace "<name>" is registered from an untrusted source` ### `Marketplace "<name>" is added but ignored` ### `Plugin <name> has a corrupt manifest file` or `has an invalid manifest file` ### `Plugin directory not found at path: <path>` ### `No plugins available` or `No marketplaces configured` ### `Marketplace "<name>" is already added from a different source` ### `Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings` ### `Failed to install: <plugin> (<reason>)` ### `Could not move the new copy of this plugin version into <path>` ### Dependency errors ### Plugin doesn't appear or its skills don't show up ### `Run /reload-plugins to apply.` ### `The packages it lists are not installed` or `were not installed, because ...` ### `Plugin "<name>" not cached at <path>` ### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read` ### `installed_plugins.json could not be read and was rebuilt` ### `install records under names that no version of Claude Code can use were removed from installed_plugins.json` ### `does not load (...), so Claude Code ignores the whole file` ### `Disabled in ~/.claude/settings.json but still loads` ### `Plugin "<name>" is enabled in project settings but isn't installed here` ### A plugin stays installed after `plugin uninstall` on Windows ### A plugin installed from a git repository shows version `unknown` ### `Failed to load hooks from <path>` and hooks that don't fire ### `Plugin directory does not exist: <path>` ### `Invalid MCP server config for "<server>"` and MCP servers that don't start ### Language server doesn't start, uses too much memory, or reports wrong diagnostics ### `commands path not found: <path>` ### `--plugin-dir` at a marketplace root doesn't load the plugins under `plugins/` ### Files the plugin references outside its directory aren't found ### `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows ### Plugin loads but its skills are missing ### Skill loads but Claude never invokes the skill ### `<directory> is not a plugin or skill folder` from `claude plugin eval init` ### The `userConfig` dialog never appears ### `claude plugin validate` reports errors ### `Plugin <name> has conflicting manifests` ### `Warning: No commands found in plugin <name> custom directory` ### Plugins with relative paths fail in URL-based marketplaces ### Marketplace validation errors ### `Marketplace source '<source>' is blocked by enterprise policy` ### `Marketplace "<name>" is not in the allowed marketplace list` ### `Plugin "<name>" is blocked by your organization's policy and cannot be installed` ### `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)` ### `Plugins from ~/.claude/skills/ are blocked by your organization's managed settings` ### `Command-sourced plugins are disabled by your organization's managed settings` ### `Marketplace '<name>' is seed-managed`
The whole hunk
from line 8, old and new numbered
/
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 8
88
99Use this page whether you install plugins, build them, host a marketplace, or administer plugins for an organization.
1010
11<Note>
12 These cases are covered on other pages:
13
14 * **Why scopes, the cache, and precedence behave the way they do**: read [Plugin loading reference](/docs/en/plugins/loading)
15 * **Looking up a flag, field, or command**: use the [plugin commands reference](/docs/en/plugins/cli-reference), the [manifest reference](/docs/en/plugins/manifest-reference), or the [marketplace reference](/docs/en/plugins/marketplace-reference)
16 * **A `hooks module not loaded` or `hooks module did not load` message**: the plugin is a [mod](/docs/en/plugins/mods/overview), so read [The mod doesn't load](/docs/en/plugins/mods/troubleshoot#the-mod-doesn’t-load)
17</Note>
11> [!NOTE]
12>
13> These cases are covered on other pages:
14>
15> * **Why scopes, the cache, and precedence behave the way they do**: read [Plugin loading reference](/docs/en/plugins/loading)
16> * **Looking up a flag, field, or command**: use the [plugin commands reference](/docs/en/plugins/cli-reference), the [manifest reference](/docs/en/plugins/manifest-reference), or the [marketplace reference](/docs/en/plugins/marketplace-reference)
17> * **A `hooks module not loaded` or `hooks module did not load` message**: the plugin is a [mod](/docs/en/plugins/mods/overview), so read [The mod doesn't load](/docs/en/plugins/mods/troubleshoot#the-mod-doesn’t-load)
1818
1919Search for the exact message you saw. Each message is listed under the stage that produces it, which isn't always the command you ran. For example, an install can fail because a marketplace is missing, so that message is under [Add a marketplace](#add-a-marketplace).
2020
from line 22
2222
2323`/plugin` is a command you type inside a running Claude Code terminal session, and it opens an interactive panel. The entries in this section cover the places where you can type it but it can't run, and the command spellings that don't exist.
2424
25<h3 id="plugin-isnt-available-in-this-environment">
26 `/plugin isn't available in this environment`
27</h3>
25### `/plugin isn't available in this environment`
2826
2927You typed `/plugin` somewhere other than a Claude Code terminal session, and Claude replied with this line instead of opening anything.
3028
from line 39
4139
4240When a terminal install works, `/plugin` prints an install summary that starts with `✓ Installed <plugin>.` and `claude plugin install` prints `Successfully installed plugin: <plugin>@<marketplace>`.
4341
44<h3 id="zsh-no-such-file-or-directory-plugin">
45 `zsh: no such file or directory: /plugin`
46</h3>
42### `zsh: no such file or directory: /plugin`
4743
4844You typed `/plugin ...` at a shell prompt, and the shell reported that no file named `/plugin` exists. Bash reports `bash: /plugin: No such file or directory`.
4945
from line 59
6359
6460To install from the shell without starting a session, run `claude plugin install <plugin>@<marketplace>` instead.
6561
66<h3 id="the-term-plugin-is-not-recognized-as-the-name-of-a-cmdlet">
67 `The term '/plugin' is not recognized as the name of a cmdlet`
68</h3>
62### `The term '/plugin' is not recognized as the name of a cmdlet`
6963
7064You typed `/plugin ...` at a PowerShell prompt, and `/plugin` is a Claude Code command, not a program. Bash and Zsh report [their own form of this error](#zsh-no-such-file-or-directory-plugin).
7165
from line 68
7468* Run `claude`, then type `/plugin` at the Claude Code prompt
7569* Run `claude plugin install <plugin>@<marketplace>` in PowerShell without starting a session
7670
77<h3 id="claude-command-not-found-after-claude-plugin">
78 `claude: command not found` after `claude plugin ...`
79</h3>
71### `claude: command not found` after `claude plugin ...`
8072
8173You ran `claude plugin install ...` in your shell, and the shell couldn't find `claude` at all. On Windows the message is `'claude' is not recognized as the name of a cmdlet` or `'claude' is not recognized as an internal or external command`.
8274
8375The cause isn't the plugin command. Follow [Verify your PATH](/docs/en/troubleshoot-install#verify-your-path), then retry the plugin command.
8476
85<h3 id="unknown-command-and-command-spellings-that-dont-exist">
86 `Unknown command` and command spellings that don't exist
87</h3>
77### `Unknown command` and command spellings that don't exist
8878
8979You typed a plugin command you saw somewhere and got `Unknown command: /<name>` in a session, or `error: unknown command '<name>'` or `error: unknown option '<flag>'` from the `claude` binary in your shell.
9080
from line 98
10898
10999A marketplace is a catalog you add to Claude Code from a git repository, a URL, or a local path. These entries cover the messages you get when adding one fails or a later refresh fails.
110100
111<h3 id="marketplace-claude-plugins-official-not-found">
112 `Marketplace "claude-plugins-official" not found`
113</h3>
101### `Marketplace "claude-plugins-official" not found`
114102
115103You ran `/plugin install <plugin>@claude-plugins-official` in a session, and Claude Code reported that it has no marketplace by that name.
116104
from line 122
134122
135123The same string also appears in the `/plugin` **Errors** tab, the panel's list of load failures, when a plugin listed in your settings names a marketplace you haven't added.
136124
137<h3 id="marketplace-not-found">
138 `Marketplace "<name>" not found`
139</h3>
125### `Marketplace "<name>" not found`
140126
141127You ran `/plugin install` in a session and Claude Code reported that it has no marketplace by that name. Two forms of the command reach this message:
142128
from line 137
151137
152138If you already added the marketplace, check the spelling against `/plugin marketplace list`.
153139
154<h3 id="invalid-marketplace-source-format">
155 `Invalid marketplace source format`
156</h3>
140### `Invalid marketplace source format`
157141
158142You ran `/plugin marketplace add <source>`, `claude plugin marketplace add <source>`, or `claude plugin install <plugin> --marketplace <source>`, and Claude Code replied `Invalid marketplace source format. Try: owner/repo, https://..., or ./path`.
159143
from line 158
174158
175159Claude Code prints `Successfully added marketplace: <name>` when the add works.
176160
177<h3 id="is-not-a-valid-github-owner-repo-shorthand">
178 `'<source>' is not a valid GitHub owner/repo shorthand`
179</h3>
161### `'<source>' is not a valid GitHub owner/repo shorthand`
180162
181163You passed a source with a slash that isn't `owner/repo`, such as `github.com/owner/repo` or a `gitlab.example.com/group/project` path. Claude Code refused it with this message and a list of accepted forms.
182164
from line 176
194176
195177A successful add prints `Successfully added marketplace: <name>`.
196178
197<h3 id="invalid-git-url">
198 `Invalid git URL`
199</h3>
179### `Invalid git URL`
200180
201181You 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.
202182
from line 186
206186
207187A 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).
208188
209<h3 id="path-does-not-exist">
210 `Path does not exist: <path>`
211</h3>
189### `Path does not exist: <path>`
212190
213191You passed a local path to `marketplace add`, and nothing exists at that path. A relative path resolves against your current directory.
214192
from line 194
216194
217195Claude Code accepts a directory that contains `.claude-plugin/marketplace.json`, or a path to a `.json` file. A path to any other file fails with `File path must point to a .json file (marketplace.json)`.
218196
219<h3 id="marketplace-file-not-found-at-claude-plugin-marketplace-json">
220 `Marketplace file not found at <path>/.claude-plugin/marketplace.json`
221</h3>
197### `Marketplace file not found at <path>/.claude-plugin/marketplace.json`
222198
223199Claude Code cloned or downloaded the marketplace but found no `marketplace.json` at the expected path inside it. The add command reports it as `Failed to add marketplace: Marketplace file not found at ...`.
224200
from line 205
229205* **You own the marketplace**: put the file at that location and re-add the marketplace
230206* **Someone else hosts it**: ask the owner for the exact source they publish
231207
232<h3 id="cannot-install-plugins-from-a-marketplace-with-this-name">
233 `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`
234</h3>
208### `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`
235209
236210You added a marketplace, and the [`name`](/docs/en/plugins/marketplace-reference#top-level-fields) in its `marketplace.json` isn't valid as the part after `@` in a [plugin id](/docs/en/plugins/loading#find-where-a-plugin-came-from) such as `my-plugin@my-marketplace`. Claude Code refuses the add and registers nothing.
237211
from line 222
248222
249223Before v2.1.295, Claude Code reported the add in this example as successful.
250224
251<h3 id="claude-code-reserves-this-name">
252 `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it`
253</h3>
225### `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it`
254226
255227You added a marketplace, and the [`name`](/docs/en/plugins/marketplace-reference#top-level-fields) in its `marketplace.json` is one of the member names that every JavaScript object has, such as `constructor`, `toString`, or `valueOf`. Claude Code reserves those names, so it refuses the add and registers nothing. [Reserved names](/docs/en/plugins/marketplace-reference#reserved-names) lists them.
256228
from line 241
269241
270242Before v2.1.296, adding such a marketplace failed with an internal error in place of this message.
271243
272<h3 id="ssh-authentication-failed-or-https-authentication-failed">
273 `SSH authentication failed` or `HTTPS authentication failed`
274</h3>
244### `SSH authentication failed` or `HTTPS authentication failed`
275245
276246You added or updated a marketplace from a git repository, and the clone failed with `Failed to clone marketplace repository:` followed by one of these lines.
277247
from line 258
288258
289259For what background auto-updates can and can't do with your credentials, see [What background auto-update does with credentials](/docs/en/plugins/host-marketplace#what-background-auto-update-does-with-credentials).
290260
291<h3 id="ssh-host-key-is-not-in-your-known-hosts-file">
292 `SSH host key is not in your known_hosts file`
293</h3>
261### `SSH host key is not in your known_hosts file`
294262
295263You added a marketplace over SSH from a host you've never connected to, and the clone failed with this line and a `ssh -T git@<host>` hint. For a host whose key changed, the message is `SSH host key has changed` with a `ssh-keygen -R <host>` hint instead.
296264
from line 270
302270
303271For a public repository, add the marketplace by its `https://` URL instead to avoid SSH entirely.
304272
305<h3 id="command-git-not-found-or-is-in-an-unsafe-location">
306 `Command 'git' not found or is in an unsafe location`
307</h3>
273### `Command 'git' not found or is in an unsafe location`
308274
309275On Windows, you added a marketplace and Claude Code reported `Failed to clone marketplace repository: Command 'git' not found or is in an unsafe location (current directory)`.
310276
311277Claude Code looks for `git` on your `PATH` and refuses to run one found only in the current directory. To fix it, install Git and retry:
312278
313<Steps>
314 <Step title="Install Git for Windows">
315 Install Git for Windows so that `git` is on your `PATH`.
316 </Step>
317
318 <Step title="Open a new terminal">
319 Open a new terminal so the updated `PATH` applies.
320 </Step>
321
322 <Step title="Confirm git runs">
323 Confirm `git --version` prints a version.
324 </Step>
325
326 <Step title="Retry the add">
327 Run the `marketplace add` command again.
328 </Step>
329</Steps>
330
331<h3 id="git-clone-timed-out-after-120s">
332 `Git clone timed out after 120s`
333</h3>
279**1. Install Git for Windows**
280
281Install Git for Windows so that `git` is on your `PATH`.
282
283**2. Open a new terminal**
284
285Open a new terminal so the updated `PATH` applies.
286
287**3. Confirm git runs**
288
289Confirm `git --version` prints a version.
290
291**4. Retry the add**
292
293Run the `marketplace add` command again.
294
295### `Git clone timed out after 120s`
334296
335297You added or updated a marketplace, and it failed with `Git clone timed out after 120s`, followed by a hint to set `CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS`.
336298
337299Cloning a marketplace, and re-cloning one to update it, gets 120 seconds by default. For a large repository or a slow connection, raise the limit. The value is in milliseconds:
338300
339<Tabs>
340 <Tab title="Bash or Zsh">
341 ```bash theme={null}
342 export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000
343 ```
344 </Tab>
345
346 <Tab title="PowerShell">
347 ```powershell theme={null}
348 $env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"
349 ```
350 </Tab>
351</Tabs>
301**Bash or Zsh**
302
303```bash theme={null}
304export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000
305```
306
307**PowerShell**
308
309```powershell theme={null}
310$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"
311```
352312
353313Then retry in the same shell.
354314
355315If the repository is a monorepo, limit the checkout to the directories you name with `claude plugin marketplace add <source> --sparse <paths>`.
356316
357<h3 id="marketplace-updates-keep-failing-offline">
358 Marketplace updates keep failing offline
359</h3>
317### Marketplace updates keep failing offline
360318
361319You work in an environment where the marketplace's git host is unreachable, and every session repeats a failed refresh in the background. Your existing checkout of the marketplace stays in place and startup isn't delayed.
362320
from line 322
364322
365323Set this variable to skip the re-clone attempt and keep using the existing checkout when the check can't reach the host:
366324
367<Tabs>
368 <Tab title="Bash or Zsh">
369 ```bash theme={null}
370 export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
371 ```
372 </Tab>
373
374 <Tab title="PowerShell">
375 ```powershell theme={null}
376 $env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"
377 ```
378 </Tab>
379</Tabs>
325**Bash or Zsh**
326
327```bash theme={null}
328export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1
329```
330
331**PowerShell**
332
333```powershell theme={null}
334$env:CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE = "1"
335```
380336
381337With the variable set, Claude Code skips the re-clone only for a checkout that already contains `.claude-plugin/marketplace.json`. A marketplace that was never cloned or whose clone stopped partway still gets the clone attempt, so add it once while online.
382338
383339For a fully offline deployment, pre-populate the plugins directory at image build time with `CLAUDE_CODE_PLUGIN_SEED_DIR` instead, following [Seed containers and CI](/docs/en/plugins/org#seed-containers-and-ci).
384340
385<h3 id="marketplace-add-fails-on-a-github-enterprise-server-host">
386 Marketplace add fails on a GitHub Enterprise Server host
387</h3>
341### Marketplace add fails on a GitHub Enterprise Server host
388342
389343You added a marketplace from a GitHub Enterprise Server (GHES) URL and got a policy error, or you added it from claude.ai and got a GitHub access error.
390344
from line 351
397351
398352You added a marketplace and ran an install, and the install stopped with a message instead of installing anything. These entries cover those messages. They also cover the related messages that appear later in the `/plugin` **Errors** tab, or as an empty **Discover** tab, when a plugin or its marketplace can't be found, read, or trusted.
399353
400<h3 id="plugin-not-found-in-marketplace">
401 `Plugin "<name>" not found in marketplace "<marketplace>"`
402</h3>
354### `Plugin "<name>" not found in marketplace "<marketplace>"`
403355
404356You ran `/plugin install <name>@<marketplace>` or `claude plugin install <name>@<marketplace>`, and the plugin name isn't in the copy of that marketplace's catalog on your machine.
405357
406358`claude plugin install` in your shell prints the same message when you haven't added the marketplace at all. If `claude plugin marketplace update <marketplace>` then answers `Marketplace '<marketplace>' not found`, [add the marketplace](#add-a-marketplace) first.
407359
408<h4 id="the-message-ends-with-a-refresh-hint">
409 `not found in marketplace` with a refresh hint
410</h4>
360#### `not found in marketplace` with a refresh hint
411361
412362The hint reads `Your local copy may be out of date — try claude plugin marketplace update <marketplace>` or `The marketplace couldn't be refreshed (...)`. Claude Code didn't refresh the marketplace before the lookup, such as when you're offline, so your copy of the catalog may be stale. Refresh with the marketplace's name, then install again:
413363
from line 367
417367
418368`claude plugin marketplace update` prints `Successfully updated marketplace: <name>`, and `/plugin marketplace update` shows `✔ Updated 1 marketplace`. If the retried install prints the same message, check the name as [`not found in marketplace` with no hint](#the-message-has-no-hint) describes. [When Claude Code refreshes a marketplace before an install](/docs/en/plugins/loading#when-claude-code-refreshes-a-marketplace-before-an-install) lists the other cases where the refresh doesn't run.
419369
420<h4 id="the-message-has-no-hint">
421 `not found in marketplace` with no hint
422</h4>
370#### `not found in marketplace` with no hint
423371
424372The name is the likeliest problem. Open `/plugin`, go to **Discover**, and copy the name from the list.
425373
426374Before v2.1.232, Claude Code refreshed the named marketplace only after the lookup missed, and only when auto-update was on for it.
427375
428<h3 id="plugin-not-found-in-any-marketplace">
429 `Plugin "<name>" not found in any marketplace`
430</h3>
376### `Plugin "<name>" not found in any marketplace`
431377
432378You ran `/plugin install <name>` with no `@marketplace`, and no registered marketplace has that plugin. `claude plugin install <name>` reports `Plugin "<name>" not found in any configured marketplace`.
433379
from line 387
441387
442388If you don't know which marketplace lists the plugin, run `/plugin marketplace list` for the marketplaces you have, and browse **Discover** in `/plugin` for the plugin name.
443389
444<h3 id="plugin-is-already-installed-globally">
445 `Plugin '<name>@<marketplace>' is already installed globally`
446</h3>
390### `Plugin '<name>@<marketplace>' is already installed globally`
447391
448392You ran `/plugin install` for a plugin that's already installed at user scope or by managed settings, and Claude Code refused with `Use '/plugin' to manage existing plugins.` If you typed the plugin name without `@<marketplace>`, the message omits `globally`.
449393
from line 397
453397
454398`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.
455399
456<h3 id="plugin-would-share-its-folder">
457 `"<plugin>" was not installed: it would share its folder with "<other>"`
458</h3>
400### `"<plugin>" was not installed: it would share its folder with "<other>"`
459401
460402You 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`.
461403
from line 408
466408* **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).
467409* **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.
468410
469<h3 id="this-plugin-uses-a-source-type-your-claude-code-version-does-not-suppo">
470 `This plugin uses a source type your Claude Code version does not support`
471</h3>
411### `This plugin uses a source type your Claude Code version does not support`
472412
473413You installed a plugin whose marketplace entry uses a source type this version of Claude Code can't fetch, and Claude Code stopped with this message and `Update Claude Code and try again.`
474414
475415Update Claude Code, then retry the install. Source types are on the [marketplace reference](/docs/en/plugins/marketplace-reference).
476416
477<h3 id="plugin-archive-integrity-check-failed">
478 `Plugin archive integrity check failed`
479</h3>
417### `Plugin archive integrity check failed`
480418
481419You installed a plugin that's distributed as a zip archive, and Claude Code refused it with this line and `The archive was not installed.` The plugin's marketplace entry uses an [`archive` source](/docs/en/plugins/marketplace-reference) with a `sha256` pin, and the downloaded file's digest doesn't match the pin.
482420
from line 429
491429* **You publish the plugin**: recompute the digest of the exact file the URL serves and update the `sha256` in the marketplace entry. Use `shasum -a 256 my-plugin.zip`, or `Get-FileHash -Algorithm SHA256 my-plugin.zip` in PowerShell
492430* **You install the plugin**: run `/plugin marketplace update <name>` in a session to refresh the catalog in case the entry was corrected, then retry the install. If the digests still disagree after the refresh, ask the marketplace owner which file they pinned before installing
493431
494<h3 id="an-npm-plugin-source-must-name-a-registry-package">
495 `An npm plugin source must name a registry package`
496</h3>
432### `An npm plugin source must name a registry package`
497433
498434A plugin whose marketplace entry uses an [`npm` source](/docs/en/plugins/marketplace-reference#npm-plugin-source) failed to install, update, or load, and the message includes this sentence. Claude Code checked the entry's `package` value before fetching anything and refused it. The message names the value and the reason:
499435
from line 442
506442* **If that's you**: change `package` to a value the [npm plugin source reference](/docs/en/plugins/marketplace-reference#npm-plugin-source) accepts, or switch the entry to a `github`, `url`, or `git-subdir` source
507443* **If it isn't you**: report the message to the marketplace owner
508444
509<h3 id="marketplace-is-registered-from-an-untrusted-source">
510 `Marketplace "<name>" is registered from an untrusted source`
511</h3>
445### `Marketplace "<name>" is registered from an untrusted source`
512446
513447A marketplace you added earlier stopped loading, and so did its plugins. This line appears in the `/plugin` **Errors** tab or on the next refresh.
514448
from line 461
527461
528462Before v2.1.205, Claude Code checked the name only when you added the marketplace, so an entry registered before its name became reserved kept loading.
529463
530<h3 id="marketplace-is-added-but-ignored">
531 `Marketplace "<name>" is added but ignored`
532</h3>
464### `Marketplace "<name>" is added but ignored`
533465
534466The marketplace has an entry in `~/.claude/plugins/known_marketplaces.json`, but the entry failed a check Claude Code runs every time it reads that file, so the marketplace and the plugins installed from it stop loading. In your shell, `claude plugin list` reports each affected plugin with a line that names the reason and the fix:
535467
from line 488
556488
557489Before v2.1.286, whatever the reason, `claude plugin list` reported such a marketplace as `Marketplace <name> not found`, and the `/plugin` **Errors** tab reported it as `Marketplace "<name>" is registered but was refused (see the debug log)`. The reason appeared only in the debug log. In v2.1.286, the reason and fix sentences used different wording, such as `Its recorded location is network-shaped or unclassifiable (never probed)`.
558490
559<h3 id="plugin-has-a-corrupt-manifest-file-or-has-an-invalid-manifest-file">
560 `Plugin <name> has a corrupt manifest file` or `has an invalid manifest file`
561</h3>
491### `Plugin <name> has a corrupt manifest file` or `has an invalid manifest file`
562492
563493Claude Code fetched the plugin, then failed to read its `.claude-plugin/plugin.json`. In the shell, the `<name>` in this line can be a temporary directory name; the `Failed to install plugin "<name>@<marketplace>"` prefix carries the plugin's real name. The wording says which check failed:
564494
from line 502
572502* **If that's you**: run `claude plugin validate <plugin-directory>` in your shell to see the same error with the offending path, then fix the file
573503* **If it isn't you**: report the message to the marketplace owner
574504
575<h3 id="plugin-directory-not-found-at-path">
576 `Plugin directory not found at path: <path>`
577</h3>
505### `Plugin directory not found at path: <path>`
578506
579507The **Errors** tab in `/plugin` shows this for an enabled plugin that its marketplace lists by a relative path, such as `./plugins/my-plugin`, when no directory exists at that path inside the marketplace. If you maintain the marketplace, correct the entry's `source` path or restore the folder. Otherwise, report the message to the marketplace owner.
580508
581509`Marketplace directory not found at path: <path>` means the marketplace's own directory is missing instead. For a marketplace you added from a local path, that directory moved or was deleted. Restore it, or remove the marketplace and add it again from its new location.
582510
583<h3 id="no-plugins-available-or-no-marketplaces-configured">
584 `No plugins available` or `No marketplaces configured`
585</h3>
511### `No plugins available` or `No marketplaces configured`
586512
587513You opened `/plugin` and the **Discover** tab is empty, or `claude plugin marketplace list` printed `No marketplaces configured`.
588514
from line 520
594520
595521Claude Code prints `Successfully added marketplace: claude-plugins-official`, and **Discover** lists its plugins. The [Anthropic marketplaces](/docs/en/plugins/anthropic-marketplaces) page lists the other marketplaces you can add.
596522
597<h3 id="marketplace-is-already-added-from-a-different-source">
598 `Marketplace "<name>" is already added from a different source`
599</h3>
523### `Marketplace "<name>" is already added from a different source`
600524
601525You named a new marketplace source with [`--marketplace <source>` on the install command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command), in a session or from your shell. The catalog Claude Code fetched from that source has the same name as a marketplace you already added from a different source. Claude Code keeps the existing marketplace instead of replacing it, and the plugin isn't installed.
602526
from line 535
611535* **The marketplace you already added**: install from it by name with `/plugin install <plugin>@<name>`
612536* **The new source**: run `/plugin marketplace remove <name>`, then retry the install
613537
614<h3 id="cannot-add-marketplace-source-doesnt-match">
615 `Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings`
616</h3>
538### `Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings`
617539
618540You added a marketplace, and the `name` in its `marketplace.json` already has an [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) entry in your user settings or managed settings. The source you gave differs from the one that entry lists, so Claude Code refuses the add and registers nothing.
619541
from line 553
631553
632554Before v2.1.287, the message read `Cannot add marketplace "<name>": its network source differs from the one declared for it in settings (kind, target, or a fetch-shaping field such as headers / ref / path / sparsePaths)`.
633555
634<h3 id="failed-to-install-from-the-plugin-menu">
635 `Failed to install: <plugin> (<reason>)`
636</h3>
556### `Failed to install: <plugin> (<reason>)`
637557
638558You selected plugins to install in the `/plugin` menu, none of them installed, and the menu closed with this summary of what failed.
639559
from line 564
644564* Fix what the reason in parentheses names
645565* When the reason was shortened, run `/plugin`, select the plugin on the **Discover** tab, and press **Enter** to install it from its details. If the install fails there, the details view shows the whole error
646566
647<h3 id="could-not-move-the-new-copy-of-this-plugin-version">
648 `Could not move the new copy of this plugin version into <path>`
649</h3>
567### `Could not move the new copy of this plugin version into <path>`
650568
651569When you install a plugin, Claude Code downloads a fresh copy of its files and moves it into that version's folder in the [plugin cache](/docs/en/plugins/loading#find-plugins-on-disk). This message means the move failed, usually because another program was using the folder while the install ran. The file-system code appears in parentheses:
652570
from line 587
669587* Close other Claude Code sessions, editors, and terminals that are using the plugin's folder under `~/.claude/plugins/cache`, then run the install again
670588* When the message says to check the plugin cache folder's permissions, restore your write permission on the folder it names and free disk space, then run the install again
671589
672<h3 id="dependency-errors">
673 Dependency errors
674</h3>
590### Dependency errors
675591
676592A plugin that declares dependencies can fail to install, or install and stay disabled, when a dependency can't be satisfied. The message reaches you at install time or at load time:
677593
from line 613
697613
698614The install succeeded, but the plugin's skills, hooks, or servers aren't doing anything. Start with [Plugin doesn't appear or its skills don't show up](#plugin-doesnt-appear-or-its-skills-dont-show-up), which tells you where Claude Code reports what it loaded, then match the message.
699615
700<h3 id="plugin-doesnt-appear-or-its-skills-dont-show-up">
701 Plugin doesn't appear or its skills don't show up
702</h3>
616### Plugin doesn't appear or its skills don't show up
703617
704618You installed a plugin and typed `/` expecting its skills, or asked Claude to use it, and nothing happened.
705619
706620Check the plugin's state before changing anything:
707621
708<Steps>
709 <Step title="Confirm the plugin is installed and enabled">
710 Run `/plugin` and open **Installed**. Confirm the plugin is listed and enabled. `claude plugin list` in your shell prints the same list with each plugin's version, scope, and `Status: ✔ enabled`.
711 </Step>
712
713 <Step title="Read the Errors tab">
714 Open the **Errors** tab in the same panel. Each entry pairs a message with a guidance line. Most messages in the rest of this section come from that tab.
715 </Step>
716
717 <Step title="Reload if you installed during this session">
718 If the plugin is installed and error-free but you installed it during this session, run `/reload-plugins`. It prints `Reloaded:` with counts of plugins, skills, agents, hooks, and servers. When something failed it adds `N errors during load. Run /plugin for details.`
719 </Step>
720</Steps>
622**1. Confirm the plugin is installed and enabled**
623
624Run `/plugin` and open **Installed**. Confirm the plugin is listed and enabled. `claude plugin list` in your shell prints the same list with each plugin's version, scope, and `Status: ✔ enabled`.
625
626**2. Read the Errors tab**
627
628Open the **Errors** tab in the same panel. Each entry pairs a message with a guidance line. Most messages in the rest of this section come from that tab.
629
630**3. Reload if you installed during this session**
631
632If the plugin is installed and error-free but you installed it during this session, run `/reload-plugins`. It prints `Reloaded:` with counts of plugins, skills, agents, hooks, and servers. When something failed it adds `N errors during load. Run /plugin for details.`
721633
722634If the plugin loads with no error and its skills still don't appear, the next step differs for your own plugin and for someone else's:
723635
724636* **A plugin you're building**: see [Plugin loads but its skills are missing](#plugin-loads-but-its-skills-are-missing)
725637* **A plugin someone else published**: open **Installed** in `/plugin` and open the plugin's details pane, which lists what the plugin contains. A plugin that lists no skills there has none to offer when you type `/`
726638
727<h3 id="run-reload-plugins-to-activate">
728 `Run /reload-plugins to apply.`
729</h3>
639### `Run /reload-plugins to apply.`
730640
731641The install summary in `/plugin` ended with `Run /reload-plugins to apply.` instead of `Plugin is now active.` A `Plugins changed. Run /reload-plugins to activate.` notice can appear above the prompt at the same time.
732642
from line 653
743653
744654Before v2.1.246, the skills count in that summary included only a plugin's `commands/` entries, so a reload could load a plugin's `SKILL.md` skills and still report `0 skills`.
745655
746<h3 id="the-packages-it-lists-are-not-installed">
747 `The packages it lists are not installed` or `were not installed, because ...`
748</h3>
656### `The packages it lists are not installed` or `were not installed, because ...`
749657
750658`/plugin` and `claude plugin list` show one of these notes on a plugin whose dependency install left no `node_modules` directory. The plugin loads, but the parts that need the missing packages may not work.
751659
from line 667
759667
760668* **`were not installed, because ...`**: the install can't run for this plugin, and the note names the reason, such as a Yarn, pnpm, or `bun.lockb` lockfile, or a lockfile whose package manager isn't installed on this computer. Updating the plugin doesn't install the packages while that reason stands. If the reason is the lockfile, the plugin's author has to replace it. If it's a missing package manager, install it, then update the plugin
761669
762<h3 id="plugin-not-cached-at">
763 `Plugin "<name>" not cached at <path>`
764</h3>
670### `Plugin "<name>" not cached at <path>`
765671
766672The **Errors** tab shows this line with the guidance `Run /plugin to refresh the plugin cache`. Claude Code has an install record for the plugin, but the directory the record points at is missing, for example after you cleared the cache.
767673
from line 679
773679
774680Then run `/reload-plugins` in your session. The **Errors** tab entry disappears and the plugin is back under **Installed**.
775681
776<h3 id="installed-plugins-json-holds-a-record-this-version-cannot-read">
777 `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`
778</h3>
682### `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`
779683
780684The message surfaces in these forms:
781685
from line 699
7956992. If you can't update, uninstall the named plugin with the version of Claude Code that wrote the record.
7967003. If neither helps, delete the record from `installed_plugins.json` by hand, then restart Claude Code or run `/reload-plugins`.
797701
798<h3 id="installed-plugins-json-could-not-be-read-and-was-rebuilt">
799 `installed_plugins.json could not be read and was rebuilt`
800</h3>
702### `installed_plugins.json could not be read and was rebuilt`
801703
802704`claude plugin list` prints this note, with the path of a kept file named `installed_plugins.unreadable.<date>.<hash>.kept`, for as long as that file sits beside `installed_plugins.json`.
803705
from line 707
805707
806708Open the `.kept` file to see what the old file recorded, and reinstall the plugins you're missing. Claude Code never reads the file back, and the file ages out on the [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) schedule.
807709
808<h3 id="install-records-under-names-that-no-version-can-use">
809 `install records under names that no version of Claude Code can use were removed from installed_plugins.json`
810</h3>
710### `install records under names that no version of Claude Code can use were removed from installed_plugins.json`
811711
812712`claude plugin list` prints this note, with the path of a copy named `installed_plugins.set-aside.<date>.<hash>.json`, for as long as that copy sits beside `installed_plugins.json`. The note ends `Nothing needs doing about these copies.`
813713
from line 715
815715
816716Claude Code copies the unusable records into the `.set-aside` file and drops them from the list. Claude Code never reads the copies back, and the copies age out on the [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) schedule.
817717
818<h3 id="does-not-load-so-claude-code-ignores-the-whole-file">
819 `does not load (...), so Claude Code ignores the whole file`
820</h3>
718### `does not load (...), so Claude Code ignores the whole file`
821719
822720The command worked. The settings file the warning names has an error, so Claude Code ignores the whole file, including anything the command wrote there, until you fix it.
823721
from line 732
834732* **`its "<key>" is not valid`**: the quoted setting holds a value Claude Code doesn't accept. Look up the setting in the [settings reference](/docs/en/settings-reference) for the values it takes. When more than one value fails, the text names the first setting and counts the others, as in `its "permissions" and 1 other value are not valid`.
835733* **`it is not a JSON object`**: the file's top level isn't a JSON object, such as a file whose top level is an array.
836734
837<h3 id="a-plugin-you-disabled-still-loads">
838 `Disabled in ~/.claude/settings.json but still loads`
839</h3>
735### `Disabled in ~/.claude/settings.json but still loads`
840736
841737You set a plugin to `false` in `~/.claude/settings.json`, and its row in `claude plugin list` or `/plugin` shows this message followed by the source that enables it, such as `— project settings enable it, which overrides your user setting`. A `true` in that higher-precedence source is overriding your user setting.
842738
from line 740
844740
845741If `claude plugin list` instead marks the plugin `required by your org`, no settings file is involved: your organization marks that synced plugin as required on claude.ai, and it loads even if you disabled it earlier. See [Plugins synced from claude.ai](/docs/en/plugins/loading#synced-plugins).
846742
847<h3 id="plugin-is-enabled-in-project-settings-but-isnt-installed-here">
848 `Plugin "<name>" is enabled in project settings but isn't installed here`
849</h3>
743### `Plugin "<name>" is enabled in project settings but isn't installed here`
850744
851745The **Errors** tab shows this line for a plugin your project's `.claude/settings.json` enables, with the guidance `Run claude plugin install <name>@<marketplace> --scope project to install it for this project`.
852746
from line 754
860754
861755If your organization pre-installs plugins for you, it does so through managed settings instead. See [Pre-install and require plugins](/docs/en/plugins/org#pre-install-and-require-plugins).
862756
863<h3 id="a-plugin-stays-installed-after-plugin-uninstall-on-windows">
864 A plugin stays installed after `plugin uninstall` on Windows
865</h3>
757### A plugin stays installed after `plugin uninstall` on Windows
866758
867759On Windows, you run `claude plugin uninstall` at project or local scope and it reports success, but `claude plugin list` or `/plugin` still lists the plugin.
868760
from line 770
878770
879771Before v2.1.295, the second run fails with `Plugin "<name>" is not installed in project scope`. Run `claude update`, then run the uninstall again.
880772
881<h3 id="failed-to-load-hooks-from-and-hooks-that-dont-fire">
882 `Failed to load hooks from <path>` and hooks that don't fire
883</h3>
773### A plugin installed from a git repository shows version `unknown`
774
775`Version: unknown` in `claude plugin list` can mean Claude Code couldn't read the commit it uses as a git-sourced plugin's version. The plugin may have its own repository or be inside a git-hosted marketplace.
776
777Run these commands in your shell, replacing `formatter@my-marketplace` with the plugin's `name@marketplace` line from `claude plugin list`:
778
779**1. Update Claude Code**
780
781[Update Claude Code](/docs/en/setup#update-claude-code) to v2.1.302 or later, which clones in a format it can read the commit from:
782
783```shell theme={null}
784claude update
785```
786
787**2. Update the marketplace**
788
789Update Claude Code's copy of the marketplace, which holds the commit for plugins inside the marketplace repository:
790
791```shell theme={null}
792claude plugin marketplace update my-marketplace
793```
794
795**3. Update the plugin**
796
797Update the plugin to rewrite its recorded version:
798
799```shell theme={null}
800claude plugin update formatter@my-marketplace
801```
802
803**4. Check the version**
804
805Check the `Version:` line for a value such as a [12-character commit ID](/docs/en/plugins/loading#how-claude-code-computes-the-version):
806
807```shell theme={null}
808claude plugin list
809```
810
811`claude plugin update` [changes one scope's block per run](/docs/en/plugins/cli-reference#which-scope-the-command-updates). For a block still showing `unknown`, rerun it with that block's `Scope:` value:
812
813```shell theme={null}
814claude plugin update formatter@my-marketplace --scope project
815```
816
817If the block still shows `unknown` after the rerun, see [Get more help](/docs/en/troubleshooting#get-more-help).
818
819### `Failed to load hooks from <path>` and hooks that don't fire
884820
885821A plugin's hooks don't run, or one blocks an action. Either the **Errors** tab shows a load failure for them, the hooks load and you see `<Event> hook error` notices or a blocking error in the transcript, or a hook loads without error and never fires.
886822
from line 847
911847
912848If a hook loads without error but never fires, first run `/plugin` in your session and open the plugin's details. A note there that begins `Its hooks.json hooks do not run` means another enabled plugin with the same name registered its hooks instead, and [Hooks when two enabled plugins share a name](/docs/en/plugins/loading#hooks-when-two-enabled-plugins-share-a-name) says which copy that is and how to switch. Otherwise, check the hook's definition and then watch it run:
913849
914<Steps>
915 <Step title="Check the event name">
916 Event names are case-sensitive, so confirm yours matches exactly, for example `PostToolUse`.
917 </Step>
918
919 <Step title="Check the matcher">
920 Confirm the hook's `matcher` matches the tool name.
921 </Step>
922
923 <Step title="Trigger the event on purpose">
924 For a `PostToolUse` hook, ask Claude to edit a file.
925 </Step>
926
927 <Step title="Read the debug log">
928 Open the [debug log](/docs/en/hooks#debug-hooks), which records which hooks matched. A hook that ran shows up there with its exit code.
929 </Step>
930</Steps>
931
932<h3 id="plugin-directory-does-not-exist">
933 `Plugin directory does not exist: <path>`
934</h3>
850**1. Check the event name**
851
852Event names are case-sensitive, so confirm yours matches exactly, for example `PostToolUse`.
853
854**2. Check the matcher**
855
856Confirm the hook's `matcher` matches the tool name.
857
858**3. Trigger the event on purpose**
859
860For a `PostToolUse` hook, ask Claude to edit a file.
861
862**4. Read the debug log**
863
864Open the [debug log](/docs/en/hooks#debug-hooks), which records which hooks matched. A hook that ran shows up there with its exit code.
865
866### `Plugin directory does not exist: <path>`
935867
936868Run `/reload-plugins` at the Claude Code prompt first, even though the message says to reinstall. A plugin's hook fails with `Failed to run: Plugin directory does not exist: <path> (<plugin> — run /plugin to reinstall)`, and the hook doesn't run, when the directory your session loaded the plugin's hooks from is gone from disk. [`Plugin directory not found at path: <path>`](#plugin-directory-not-found-at-path) is a different message, about a marketplace entry.
937869
from line 873
941873* **`N errors during load. Run /plugin for details.`**: open the **Errors** tab in `/plugin` and follow this page's entry for the message it shows
942874* **A line that ends `Run /reload-plugins --force to apply.`**: nothing reloaded, and the hooks keep failing. Run `/reload-plugins --force` at the Claude Code prompt
943875
944<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">
945 `Invalid MCP server config for "<server>"` and MCP servers that don't start
946</h3>
876### `Invalid MCP server config for "<server>"` and MCP servers that don't start
947877
948878A plugin bundles an MCP server, and the **Errors** tab shows `Invalid MCP server config for "<server>": <error>`, or the server is listed but `/mcp` never shows it connected.
949879
from line 909
979909
980910For paths that reach outside the plugin directory, see [Files the plugin references outside its directory aren't found](#files-the-plugin-references-outside-its-directory-arent-found).
981911
982<h3 id="language-server-doesnt-start">
983 Language server doesn't start, uses too much memory, or reports wrong diagnostics
984</h3>
912### Language server doesn't start, uses too much memory, or reports wrong diagnostics
985913
986914You installed a [code intelligence plugin](/docs/en/plugins/code-intelligence) and Claude isn't seeing diagnostics, or the language server is using too much memory or reporting errors that aren't real.
987915
from line 938
1010938* **A hook that doesn't fire**: see [hooks that don't fire](#failed-to-load-hooks-from-and-hooks-that-dont-fire)
1011939* **An MCP server that doesn't start**: see [MCP servers that don't start](#invalid-mcp-server-config-for-and-mcp-servers-that-dont-start)
1012940
1013<h3 id="commands-path-not-found">
1014 `commands path not found: <path>`
1015</h3>
941### `commands path not found: <path>`
1016942
1017943The **Errors** tab shows `commands path not found: <absolute path>` with the guidance `Check that the path in your manifest or marketplace config is correct`. The same message appears for `skills`, `agents`, and `hooks`.
1018944
from line 946
1020946
1021947Paths in the manifest are relative to the plugin root and start with `./`. A path that resolves outside the plugin root is reported as `<component> path escapes plugin directory` instead and is dropped.
1022948
1023<h3 id="plugin-dir-loads-a-plugin-with-no-components">
1024 `--plugin-dir` at a marketplace root doesn't load the plugins under `plugins/`
1025</h3>
949### `--plugin-dir` at a marketplace root doesn't load the plugins under `plugins/`
1026950
1027951You started `claude --plugin-dir <path>` and see no error, but the plugin's skills, agents, and hooks aren't there.
1028952
from line 958
1034958
1035959Then open **Installed** in `/plugin`, where the plugin's details pane lists its components.
1036960
1037<h3 id="files-the-plugin-references-outside-its-directory-arent-found">
1038 Files the plugin references outside its directory aren't found
1039</h3>
961### Files the plugin references outside its directory aren't found
1040962
1041963A plugin works from its source directory with `--plugin-dir` but fails after install, with errors about a path such as `../shared-utils`.
1042964
1043965Claude Code copies an installed plugin into its cache and loads it from there, so a path that reaches outside the plugin's own directory points at nothing in the cache. Move the shared files inside the plugin directory, or reference them through a symlink inside it. For where the cache is and how paths resolve, see [Find plugins on disk](/docs/en/plugins/loading#find-plugins-on-disk).
1044966
1045<h3 id="claude-plugin-root-shows-forward-slashes-on-windows">
1046 `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows
1047</h3>
967### `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows
1048968
1049969On Windows, a plugin hook receives `${CLAUDE_PLUGIN_ROOT}` as `C:/Users/you/...` rather than `C:\Users\you\...`, and a script that expected backslashes breaks.
1050970
from line 975
1055975* An exec-form hook, which spawns the process directly with an `args` array
1056976* A hook with `"shell": "powershell"`
1057977
1058<h3 id="plugin-loads-but-its-skills-are-missing">
1059 Plugin loads but its skills are missing
1060</h3>
978### Plugin loads but its skills are missing
1061979
1062980Your plugin is listed under **Installed** with no errors, but its skills aren't offered when you type `/`.
1063981
from line 983
1065983
1066984Each skill is a directory containing `SKILL.md`. A `skills` entry in the manifest that points at a `SKILL.md` file rather than its directory is reported as `path is a file; skills entries must be directories containing SKILL.md`.
1067985
1068<h3 id="skill-loads-but-claude-never-invokes-the-skill">
1069 Skill loads but Claude never invokes the skill
1070</h3>
986### Skill loads but Claude never invokes the skill
1071987
1072988Your plugin's skill runs when you type its `/<plugin>:<skill>` command, but Claude never invokes it in response to a plain request.
1073989
from line 995
1079995
1080996To measure how often the skill triggers across realistic prompts rather than checking one at a time, write an eval case with a [`tool_used: Skill` grader](/docs/en/plugin-evals#create-your-first-eval-suite) and run it with `claude plugin eval` after each description change.
1081997
1082<h3 id="is-not-a-plugin-or-skill-folder">
1083 `<directory> is not a plugin or skill folder` from `claude plugin eval init`
1084</h3>
998### `<directory> is not a plugin or skill folder` from `claude plugin eval init`
1085999
10861000You ran `claude plugin eval init` from a directory that isn't a plugin's root, such as your home directory or the root of a repository that keeps the plugin in a subdirectory. `init` writes the suite under the working directory, so it stops instead of creating an `evals/` directory the plugin would never see.
10871001
10881002Change to the plugin's root, the directory that holds `.claude-plugin/plugin.json` or the skill's `SKILL.md`, and run the command again. To scaffold the suite somewhere else on purpose, pass `--eval-dir`. See [Test plugins with evals](/docs/en/plugin-evals).
10891003
1090<h3 id="the-userconfig-dialog-never-appears">
1091 The `userConfig` dialog never appears
1092</h3>
1004### The `userConfig` dialog never appears
10931005
10941006Your plugin declares `userConfig` options, but no configuration dialog appears when you install it.
10951007
from line 1025
11131025
11141026For 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.
11151027
1116<h3 id="claude-plugin-validate-reports-errors">
1117 `claude plugin validate` reports errors
1118</h3>
1028### `claude plugin validate` reports errors
11191029
11201030You ran `claude plugin validate <path>`, or `/plugin validate <path>` in a session, and it printed `Found N errors` and `Validation failed`, then exited with code 1.
11211031
from line 1049
11391049
11401050`plugin.json` fields are on the [manifest reference](/docs/en/plugins/manifest-reference), and marketplace-level messages are under [Marketplace validation errors](#marketplace-validation-errors).
11411051
1142<h3 id="plugin-has-conflicting-manifests">
1143 `Plugin <name> has conflicting manifests`
1144</h3>
1052### `Plugin <name> has conflicting manifests`
11451053
11461054The plugin fails to load with `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.`
11471055
11481056The plugin has its own `plugin.json`, and its marketplace entry sets `strict: false` while also declaring any of `commands`, `agents`, `skills`, `hooks`, `outputStyles`, or `themes`. Remove those fields from the entry, or set `strict: true` in the entry so Claude Code appends them to `plugin.json`. See [Strict mode](/docs/en/plugins/marketplace-reference#strict-mode).
11491057
1150<h3 id="warning-no-commands-found-in-plugin-custom-directory">
1151 `Warning: No commands found in plugin <name> custom directory`
1152</h3>
1058### `Warning: No commands found in plugin <name> custom directory`
11531059
11541060When the plugin loads, the `claude --debug` log at `~/.claude/debug/<session-id>.txt` records `Warning: No commands found in plugin <name> custom directory: <path>. Expected .md files or SKILL.md in subdirectories.` Nothing appears in the session or the **Errors** tab.
11551061
from line 1065
11591065
11601066You publish a marketplace and a user reports an error, or your own validation fails. These entries are for the marketplace owner.
11611067
1162<h3 id="plugins-with-relative-paths-fail-in-url-based-marketplaces">
1163 Plugins with relative paths fail in URL-based marketplaces
1164</h3>
1068### Plugins with relative paths fail in URL-based marketplaces
11651069
11661070Users added your marketplace with an `https://example.com/marketplace.json` URL. Installs of plugins whose `source` is a relative path, such as `./plugins/my-plugin`, fail with `its marketplace entry path does not stay inside the marketplace directory`. Already-installed plugins fail to load with `Plugin source path refused`. Both messages have an [error reference entry](/docs/en/errors#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).
11671071
from line 1077
11731077
11741078Alternatively, host the marketplace in a git repository and tell users to add it with the repository URL. For a git source, Claude Code clones the whole repository, so relative paths resolve. Source types are on the [marketplace reference](/docs/en/plugins/marketplace-reference).
11751079
1176<h3 id="marketplace-validation-errors">
1177 Marketplace validation errors
1178</h3>
1080### Marketplace validation errors
11791081
11801082You ran `claude plugin validate .` from your marketplace directory and it reported errors or warnings on the marketplace file itself.
11811083
from line 1106
12041106
12051107Your organization deploys managed settings that restrict plugins, and a command was refused with a policy message. These entries name the setting behind each refusal so you know what to ask your administrator for. For the admin side, see [Manage plugins for your organization](/docs/en/plugins/org).
12061108
1207<h3 id="marketplace-source-is-blocked-by-enterprise-policy">
1208 `Marketplace source '<source>' is blocked by enterprise policy`
1209</h3>
1109### `Marketplace source '<source>' is blocked by enterprise policy`
12101110
12111111You ran `/plugin marketplace add`, `update`, or an install, and Claude Code refused with this line. For a GitHub or git source, the host follows the source in parentheses, as in `'github:owner/repo' (github.com)`.
12121112
from line 1120
12201120
12211121A marketplace you added before the policy became more restrictive stops refreshing too, because the policy applies on every refresh.
12221122
1223<h3 id="marketplace-is-not-in-the-allowed-marketplace-list">
1224 `Marketplace "<name>" is not in the allowed marketplace list`
1225</h3>
1123### `Marketplace "<name>" is not in the allowed marketplace list`
12261124
12271125The **Errors** tab shows this line, or `Marketplace "<name>" is blocked by enterprise policy`, for a marketplace you already have registered.
12281126
12291127The same managed settings that block a [marketplace source](#marketplace-source-is-blocked-by-enterprise-policy) apply at load time. `strictKnownMarketplaces` doesn't include this marketplace, or `blockedMarketplaces` names it, so Claude Code stops loading it and its plugins. For the allowlist variant, the guidance line shows the allowed sources, or `Contact your administrator to configure allowed marketplace sources`. For the blocklist variant it reads `This marketplace source is explicitly blocked by your administrator`.
12301128
1231<h3 id="plugin-is-blocked-by-your-organizations-policy-and-cannot-be-installed">
1232 `Plugin "<name>" is blocked by your organization's policy and cannot be installed`
1233</h3>
1129### `Plugin "<name>" is blocked by your organization's policy and cannot be installed`
12341130
12351131An install was refused with this line, an enable with the same line ending `cannot be enabled`, or an install or update with one naming the reason: `Plugin "<name>" is from marketplace "<marketplace>", which is blocked by your organization's policy`, or `Plugin "<name>" depends on "<dep>", which is blocked by your organization's policy`.
12361132
12371133Managed settings block this plugin, its marketplace, or a dependency it needs. Ask your administrator which entry applies. A blocked dependency means the plugin can't install until the dependency's marketplace is allowed.
12381134
1239<h3 id="plugin-dir-is-disabled-by-your-organizations-managed-settings-disables">
1240 `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`
1241</h3>
1135### `--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)`
12421136
12431137You started `claude` with `--plugin-dir`, `--plugin-url`, `--agents`, or `--mcp-config`. Claude Code exited with this message and `Plugins, custom agents, and MCP servers can only be loaded from sources your administrator has approved.`
12441138
from line 1140
12461140
12471141A related message in the `/plugin` **Errors** tab is `--plugin-dir copy of "<name>" ignored: plugin is locked by managed settings`. Managed settings enable or disable that plugin by name, and Claude Code ignores your `--plugin-dir` copy of it so the flag can't override the policy.
12481142
1249<h3 id="plugins-from-claude-skills-are-blocked-by-your-organizations-managed-s">
1250 `Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`
1251</h3>
1143### `Plugins from ~/.claude/skills/ are blocked by your organization's managed settings`
12521144
12531145You ran `claude plugin init` or `claude plugin enable`, and it stopped with this line. The message names `strictKnownMarketplaces or blockedMarketplaces` and asks your administrator to add `{"source":"skills-dir"}` to `strictKnownMarketplaces` or remove it from `blockedMarketplaces`.
12541146
12551147The `skills-dir` source stands for plugins Claude Code loads from your `~/.claude/skills/` directory. Ask your administrator to make the change the message names.
12561148
1257<h3 id="command-sourced-plugins-are-disabled-by-your-organizations-managed-set">
1258 `Command-sourced plugins are disabled by your organization's managed settings`
1259</h3>
1149### `Command-sourced plugins are disabled by your organization's managed settings`
12601150
12611151You installed or updated a plugin with a `command` source, and it stopped with this line and `The plugin was not installed or updated and its command was not run.`
12621152
12631153Your administrator set `disableCommandPluginSources`, so Claude Code refuses to run the marketplace-declared command that produces the plugin. Setting `allowManagedHooksOnly` alone has the same effect when `disableCommandPluginSources` is unset. Ask your administrator whether the plugin can be published from a source type the policy allows.
12641154
1265<h3 id="marketplace-is-seed-managed">
1266 `Marketplace '<name>' is seed-managed`
1267</h3>
1155### `Marketplace '<name>' is seed-managed`
12681156
12691157You ran `claude plugin marketplace update <name>`, and it failed with `Marketplace '<name>' is seed-managed (<dir>)` and a hint to ask your admin.
12701158
12711159
No line in this hunk matches that.