Home Docs Claude Code CLI 21 Oct 2026

One change · claude-code

Troubleshoot plugins changedplugins/troubleshooting

Nearest release: v2.1.307, published 4 hours 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 21 Oct 2026 16:44 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 22 Oct 2026 18:07 UTC.

Upstream edited 21 Oct 2026 16:44 UTC

Recorded here 22 Oct 2026 18:07 UTC

Lines+78added

Lines−78removed

From line 12 where the diff opens

First seen 25 Sep 2026 this site's first read of the page

Recorded edits28to this page, all time

The whole hunk

from line 12, old and new numbered

lines

from line 12

1212>

1313> These cases are covered on other pages:

1414>

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)

15> * **Why scopes, the cache, and precedence behave the way they do**: read [Plugin loading reference](/docs/en/plugins/loading.md)

16> * **Looking up a flag, field, or command**: use the [plugin commands reference](/docs/en/plugins/cli-reference.md), the [manifest reference](/docs/en/plugins/manifest-reference.md), or the [marketplace reference](/docs/en/plugins/marketplace-reference.md)

17> * **A `hooks module not loaded` or `hooks module did not load` message**: the plugin is a [mod](/docs/en/plugins/mods/overview.md), so read [The mod doesn't load](/docs/en/plugins/mods/troubleshoot.md#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 26

2626

2727You typed `/plugin` somewhere other than a Claude Code terminal session, and Claude replied with this line instead of opening anything.

2828

29You get this reply in a session that has no terminal to draw the `/plugin` panel in: [non-interactive mode](/docs/en/headless) with `claude -p`, the Agent SDK, the Claude desktop app's Code tab, the VS Code extension panel, and the browser at claude.ai/code.

29You get this reply in a session that has no terminal to draw the `/plugin` panel in: [non-interactive mode](/docs/en/headless.md) with `claude -p`, the Agent SDK, the Claude desktop app's Code tab, the VS Code extension panel, and the browser at claude.ai/code.

3030

3131In the VS Code extension panel, only a `/plugin` line with something after it, such as `/plugin install <plugin>@<marketplace>`, gets this reply. `/plugin` or `/plugins` typed alone opens the **Manage plugins** dialog.

3232

3333Install the plugin from the surface you're on instead:

3434

35* **Claude desktop app, local or SSH session**: use the **Desktop app** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin)

36* **VS Code extension**: use the **VS Code** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin)

37* **Claude Code on the web, or a desktop cloud session**: a cloud session has no plugin browser. See the **Cloud session** tab under [Install a plugin](/docs/en/plugins/install#install-a-plugin) for what a cloud session loads

35* **Claude desktop app, local or SSH session**: use the **Desktop app** tab under [Install a plugin](/docs/en/plugins/install.md#install-a-plugin)

36* **VS Code extension**: use the **VS Code** tab under [Install a plugin](/docs/en/plugins/install.md#install-a-plugin)

3838* **A terminal you have access to**: run `claude` and type `/plugin` there, or run `claude plugin install <plugin>@<marketplace>` in your shell without starting a session

3939

4040When a terminal install works, `/plugin` prints an install summary that starts with `✓ Installed <plugin>.` and `claude plugin install` prints `Successfully installed plugin: <plugin>@<marketplace>`.

from line 72

7272

7373You 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`.

7474

75The cause isn't the plugin command. Follow [Verify your PATH](/docs/en/troubleshoot-install#verify-your-path), then retry the plugin command.

75The cause isn't the plugin command. Follow [Verify your PATH](/docs/en/troubleshoot-install.md#verify-your-path), then retry the plugin command.

7676

7777### `Unknown command` and command spellings that don't exist

7878

7979You 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.

8080

81Several command spellings are in use that Claude Code doesn't have. The table below maps each one to the real command. The [plugin commands reference](/docs/en/plugins/cli-reference) lists the subcommands and their flags.

8282

8383| You typed | What Claude Code says | Use instead |

8484| :- | :- | :- |

from line 127

127127You 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:

128128

129129* **`/plugin install <plugin>@<name>`**: the install line, often one someone sent you, names a marketplace you haven't added. The rest of this entry covers finding and adding it.

130* **`/plugin install <source>` with a path, URL, or `owner/repo`**: this form reports the message instead of installing, even for a source you've already added. To install from a source in one command, see [Add a marketplace and install in one command](/docs/en/plugins/install#add-a-marketplace-and-install-in-one-command).

131131

132If the name starts with `claudeai-`, the marketplace is hosted on claude.ai, and you add it by name from your shell with `claude plugin marketplace add --claudeai <name>`. See [Add a marketplace from claude.ai](/docs/en/plugins/install#add-from-claude-ai).

133133

134For any other name, an install line names a marketplace but doesn't say where the marketplace is hosted, and Claude Code has no index to look a marketplace name up in. Ask whoever sent the line for the marketplace's source, which is a GitHub `owner/repo`, a git URL, or a path. Then [add the marketplace](/docs/en/plugins/install#add-a-marketplace) and run the install line again.

134For any other name, an install line names a marketplace but doesn't say where the marketplace is hosted, and Claude Code has no index to look a marketplace name up in. Ask whoever sent the line for the marketplace's source, which is a GitHub `owner/repo`, a git URL, or a path. Then [add the marketplace](/docs/en/plugins/install.md#add-a-marketplace) and run the install line again.

135135

136A marketplace someone sends you is third-party, so [review the plugin before you install it](/docs/en/plugins/security#review-a-plugin-before-you-install).

136A marketplace someone sends you is third-party, so [review the plugin before you install it](/docs/en/plugins/security.md#review-a-plugin-before-you-install).

137137

138138If you already added the marketplace, check the spelling against `/plugin marketplace list`.

139139

from line 198

198198

199199Claude 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 ...`.

200200

201The default location is `.claude-plugin/marketplace.json` at the repository root, and the [marketplace reference](/docs/en/plugins/marketplace-reference) lists the accepted locations.

201The default location is `.claude-plugin/marketplace.json` at the repository root, and the [marketplace reference](/docs/en/plugins/marketplace-reference.md) lists the accepted locations.

202202

203203The fix differs for the owner and for everyone else:

204204

from line 207

207207

208208### `Cannot add marketplace "<name>": Claude Code cannot install plugins from a marketplace with this name`

209209

210You 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.

210You 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.md#find-where-a-plugin-came-from) such as `my-plugin@my-marketplace`. Claude Code refuses the add and registers nothing.

211211

212212The rest of the message states the rule for the name. In this example, `_internal` breaks the rule by starting with `_`:

213213

from line 224

224224

225225### `Cannot add marketplace "<name>": Claude Code reserves this name and cannot register a marketplace under it`

226226

227You 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.

228228

229229In this example, the marketplace is named `constructor`:

230230

from line 256

256256

257257To make Claude Code skip SSH for GitHub `owner/repo` sources, set `CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1`. Without it, Claude Code clones those sources over SSH when an SSH key for `github.com` looks configured, and falls back to HTTPS when the SSH clone fails.

258258

259For 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).

259For 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.md#what-background-auto-update-does-with-credentials).

260260

261261### `SSH host key is not in your known_hosts file`

262262

from line 318

318318

319319You 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.

320320

321Each session, for a marketplace with [auto-update on](/docs/en/plugins/loading#which-marketplaces-and-plugins-auto-update), Claude Code checks the marketplace's git host for new commits in the background. When that check can't reach the host, it tries to clone the marketplace again, and offline that clone fails too.

321Each session, for a marketplace with [auto-update on](/docs/en/plugins/loading.md#which-marketplaces-and-plugins-auto-update), Claude Code checks the marketplace's git host for new commits in the background. When that check can't reach the host, it tries to clone the marketplace again, and offline that clone fails too.

322322

323323Set this variable to skip the re-clone attempt and keep using the existing checkout when the check can't reach the host:

324324

from line 336

336336

337337With 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.

338338

339For 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).

340340

341341### Marketplace add fails on a GitHub Enterprise Server host

342342

from line 344

344344

345345Both cases are on the GHES page:

346346

347* [A policy error](/docs/en/github-enterprise-server#marketplace-add-fails-with-a-policy-error) means your organization restricted marketplace sources and an admin needs to add a `hostPattern` for the host

348* [A GitHub access error on claude.ai](/docs/en/github-enterprise-server#marketplace-add-on-claude-ai-fails-with-a-github-access-error) means your own GitHub Enterprise account isn't connected yet

347* [A policy error](/docs/en/github-enterprise-server.md#marketplace-add-fails-with-a-policy-error) means your organization restricted marketplace sources and an admin needs to add a `hostPattern` for the host

348* [A GitHub access error on claude.ai](/docs/en/github-enterprise-server.md#marketplace-add-on-claude-ai-fails-with-a-github-access-error) means your own GitHub Enterprise account isn't connected yet

349349

350350## Install a plugin

351351

from line 365

365365/plugin marketplace update <marketplace>

366366```

367367

368`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.

368`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.md#when-claude-code-refreshes-a-marketplace-before-an-install) lists the other cases where the refresh doesn't run.

369369

370370#### `not found in marketplace` with no hint

371371

from line 391

391391

392392You 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`.

393393

394The plugin is already available in every project, so there's nothing to add. To change its [scope](/docs/en/plugins/install), enable or disable it, or configure it, open `/plugin` and go to **Installed**.

394The plugin is already available in every project, so there's nothing to add. To change its [scope](/docs/en/plugins/install.md), enable or disable it, or configure it, open `/plugin` and go to **Installed**.

395395

396396A plugin installed only at project or local scope doesn't trigger this message. Claude Code lets you install it at user scope as well, so it's available in other projects.

397397

from line 405

405405

406406The message names the way out:

407407

408* **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).

409409* **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.

410410

411411### `This plugin uses a source type your Claude Code version does not support`

from line 412

412412

413413You 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.`

414414

415Update Claude Code, then retry the install. Source types are on the [marketplace reference](/docs/en/plugins/marketplace-reference).

415Update Claude Code, then retry the install. Source types are on the [marketplace reference](/docs/en/plugins/marketplace-reference.md).

416416

417417### `Plugin archive integrity check failed`

418418

from line 439

439439

440440The marketplace's owner has to change the entry:

441441

442* **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

442* **If that's you**: change `package` to a value the [npm plugin source reference](/docs/en/plugins/marketplace-reference.md#npm-plugin-source) accepts, or switch the entry to a `github`, `url`, or `git-subdir` source

443443* **If it isn't you**: report the message to the marketplace owner

444444

445445### `Marketplace "<name>" is registered from an untrusted source`

from line 446

446446

447447A marketplace you added earlier stopped loading, and so did its plugins. This line appears in the `/plugin` **Errors** tab or on the next refresh.

448448

449The marketplace is registered under a name that is [reserved for official Anthropic marketplaces](/docs/en/plugins/marketplace-reference), but its registered source isn't an `anthropics` GitHub repository. Reserved names are re-checked every time a marketplace loads or refreshes, so the marketplace and the plugins installed from it stop loading.

449The marketplace is registered under a name that is [reserved for official Anthropic marketplaces](/docs/en/plugins/marketplace-reference.md), but its registered source isn't an `anthropics` GitHub repository. Reserved names are re-checked every time a marketplace loads or refreshes, so the marketplace and the plugins installed from it stop loading.

450450

451451The full message names the reserved name and the fix:

452452

from line 477

477477* `Its git URL can't be used: <reason>` or `Its URL can't be read as an https:// or http:// address`: the entry's recorded source URL is one Claude Code refuses to clone or fetch from

478478* `Its source doesn't match its extraKnownMarketplaces entry in user or managed settings`: the entry doesn't match the [`extraKnownMarketplaces`](/docs/en/settings-reference#extraknownmarketplaces) declaration of the same name

479479

480When `(see the debug log)` follows `is added but ignored` in place of a reason, Claude Code refuses the marketplace's name, such as [another spelling of a reserved name](/docs/en/errors#marketplace-name-is-another-spelling-of-a-reserved-name). The [debug log](/docs/en/debug-your-config) names the entry.

480When `(see the debug log)` follows `is added but ignored` in place of a reason, Claude Code refuses the marketplace's name, such as [another spelling of a reserved name](/docs/en/errors.md#marketplace-name-is-another-spelling-of-a-reserved-name). The [debug log](/docs/en/debug-your-config.md) names the entry.

481481

482482**What to do:**

483483

from line 518

518518/plugin marketplace add anthropics/claude-plugins-official

519519```

520520

521Claude 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.

522522

523523### `Marketplace "<name>" is already added from a different source`

524524

from line 541

541541

542542Two sources match when they have the same type and the same value in every field. An entry that sets a `ref` you didn't pass counts as different. A `github` entry also counts as different when you gave the repository as an `https://github.com/` URL, because Claude Code records that URL as a [`git` source](/docs/en/plugins/marketplace-reference#marketplace-sources). Do one of these:

543543

544* **Use the declared source**: Claude Code [registers marketplaces declared in settings](/docs/en/settings-reference#extraknownmarketplaces) on its own, so first run `/plugin marketplace list` in a session. If the list shows the name, the marketplace is already registered and there's nothing to add.

544* **Use the declared source**: Claude Code [registers marketplaces declared in settings](/docs/en/settings-reference.md#extraknownmarketplaces) on its own, so first run `/plugin marketplace list` in a session. If the list shows the name, the marketplace is already registered and there's nothing to add.

545545

546546 If the list doesn't show it, add it with the source typed the way the entry writes it. For an entry whose `source` object is `{ "source": "github", "repo": "acme-corp/claude-plugins", "ref": "v1.2.0" }`, run this:

547547

from line 566

566566

567567### `Could not move the new copy of this plugin version into <path>`

568568

569When 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:

569When 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.md#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:

570570

571571```text theme={null}

572572Could not move the new copy of this plugin version into /home/user/.claude/plugins/cache/acme-tools/formatter/1.2.0: the new copy or the version folder stayed busy while the install ran (ENOTEMPTY) — usually a scanner still reading the freshly downloaded files, another program using that folder, or another process re-creating it. The previously installed copy was moved back. Run the install again once other Claude Code sessions or programs using that folder have finished.

from line 594

594594* **During install**: the refusal comes back as the install's error message

595595* **When the plugin loads**: the problem appears in `claude plugin list` and the `/plugin` **Errors** tab, and Claude Code keeps the affected plugin disabled until you resolve it

596596

597The table lists each message and its fix. To declare dependencies as an author, see [Plugin dependencies](/docs/en/plugins/dependencies).

597The table lists each message and its fix. To declare dependencies as an author, see [Plugin dependencies](/docs/en/plugins/dependencies.md).

598598

599599| Message | Meaning | How to resolve |

600600| :- | :- | :- |

from line 640

640640

641641The 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.

642642

643Claude Code didn't activate the plugin during the install, either because activating it would [invalidate the prompt cache](/docs/en/prompt-caching#enabling-or-disabling-a-plugin) or because the activation attempt failed.

643Claude Code didn't activate the plugin during the install, either because activating it would [invalidate the prompt cache](/docs/en/prompt-caching.md#enabling-or-disabling-a-plugin) or because the activation attempt failed.

644644

645645You don't need to type the command. The panel closes and Claude Code runs `/reload-plugins` for you, or queues it until the response that's streaming finishes.

646646

from line 719

719719

720720The 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.

721721

722Fix the error the warning names. For a value Claude Code doesn't accept, [Fix a broken settings file](/docs/en/settings#fix-a-broken-settings-file) says how. Then run the command again if its change is no longer in the file.

722Fix the error the warning names. For a value Claude Code doesn't accept, [Fix a broken settings file](/docs/en/settings.md#fix-a-broken-settings-file) says how. Then run the command again if its change is no longer in the file.

723723

724724The warning follows the success line of `claude plugin install`, `enable`, `disable`, or `claude plugin marketplace add` in your shell:

725725

from line 729

729729

730730The text in parentheses names the error:

731731

732* **`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`.

732* **`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.md) 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`.

733733* **`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.

734734

735735### `Disabled in ~/.claude/settings.json but still loads`

from line 736

736736

737737You 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.

738738

739To opt out of a project-enabled plugin on your machine, set the id to `false` in `.claude/settings.local.json`, which has higher precedence than the project file. For the other sources the message can name, see [Disabled in user settings but still loads](/docs/en/plugins/loading#disabled-in-user-settings-but-still-loads).

740740

741If `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).

742742

743743### `Plugin "<name>" is enabled in project settings but isn't installed here`

744744

from line 752

752752

753753After you run `/reload-plugins` in your session, the **Errors** tab entry is gone and the plugin is listed under **Installed**.

754754

755If 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).

755If your organization pre-installs plugins for you, it does so through managed settings instead. See [Pre-install and require plugins](/docs/en/plugins/org.md#pre-install-and-require-plugins).

756756

757757### A plugin stays installed after `plugin uninstall` on Windows

758758

from line 778

778778

779779**1. Update Claude Code**

780780

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:

781[Update Claude Code](/docs/en/setup.md#update-claude-code) to v2.1.302 or later, which clones in a format it can read the commit from:

782782

783783```shell theme={null}

784784claude update

from line 802

802802

803803**4. Check the version**

804804

805Check the `Version:` line for a value such as a [12-character commit ID](/docs/en/plugins/loading#how-claude-code-computes-the-version):

805Check the `Version:` line for a value such as a [12-character commit ID](/docs/en/plugins/loading.md#how-claude-code-computes-the-version):

806806

807807```shell theme={null}

808808claude plugin list

809809```

810810

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:

811`claude plugin update` [changes one scope's block per run](/docs/en/plugins/cli-reference.md#which-scope-the-command-updates). For a block still showing `unknown`, rerun it with that block's `Scope:` value:

812812

813813```shell theme={null}

814814claude plugin update formatter@my-marketplace --scope project

815815```

816816

817If the block still shows `unknown` after the rerun, see [Get more help](/docs/en/troubleshooting#get-more-help).

817If the block still shows `unknown` after the rerun, see [Get more help](/docs/en/troubleshooting.md#get-more-help).

818818

819819### `Failed to load hooks from <path>` and hooks that don't fire

820820

from line 826

826826

827827* **`Failed to load hooks from <path>: <reason>`**: `hooks/hooks.json` isn't valid JSON or fails the hooks schema. The reason names the parse or validation error. Fix the file. To catch a JSON syntax problem in `hooks/hooks.json` before you publish the plugin, run `claude plugin validate <plugin-directory>` in your shell

828828* **`hooks path not found: <path>`**: the manifest's `hooks` field names a file that doesn't exist at that path relative to the plugin root. Fix the path or add the file

829* **`hooks path escapes plugin directory: <path>`**: see [Path escapes plugin directory](/docs/en/errors#path-escapes-plugin-directory)

829* **`hooks path escapes plugin directory: <path>`**: see [Path escapes plugin directory](/docs/en/errors.md#path-escapes-plugin-directory)

830830

831831#### `hook error` notices in the transcript

832832

833833A notice of the form `... hook error: Failed with non-blocking status code: <stderr>` means the hook ran and its command failed. For example, `Stop hook error: Failed with non-blocking status code: /bin/sh: node: command not found` means the shell Claude Code spawned couldn't find `node`. Install it, or make sure it's on the `PATH` of the terminal you start `claude` from.

834834

835If the stderr shows the plugin's path cut off at a space, the hook's shell-form command uses `${CLAUDE_PLUGIN_ROOT}` outside quotes and the install path contains a space. Wrap the variable in double quotes or use [exec form](/docs/en/hooks#exec-form-and-shell-form). To find the unquoted variable, run `claude plugin validate` on the plugin's directory and look for its [quoting warning](/docs/en/plugins/manifest-reference#quoting-and-path-separators).

835If the stderr shows the plugin's path cut off at a space, the hook's shell-form command uses `${CLAUDE_PLUGIN_ROOT}` outside quotes and the install path contains a space. Wrap the variable in double quotes or use [exec form](/docs/en/hooks.md#exec-form-and-shell-form). To find the unquoted variable, run `claude plugin validate` on the plugin's directory and look for its [quoting warning](/docs/en/plugins/manifest-reference.md#quoting-and-path-separators).

836836

837837If the notice reads `Failed to run: Plugin directory does not exist: <path>`, see [`Plugin directory does not exist`](#plugin-directory-does-not-exist).

838838

839For any other error, run the hook's command yourself from the plugin directory to see the full output, or capture the full stderr with [debug logging](/docs/en/hooks#debug-hooks).

839For any other error, run the hook's command yourself from the plugin directory to see the full output, or capture the full stderr with [debug logging](/docs/en/hooks.md#debug-hooks).

840840

841841#### A plugin hook blocks a tool call or prompt

842842

843A hook that exits with code 2 [blocks the action it ran for](/docs/en/hooks#exit-code-2). When a plugin's hook blocks this way and its stderr is the blocking message, the error ends with `This hook comes from the <plugin> plugin.` so that you know which plugin to disable or fix. Before v2.1.281, the error didn't name the plugin.

843A hook that exits with code 2 [blocks the action it ran for](/docs/en/hooks.md#exit-code-2). When a plugin's hook blocks this way and its stderr is the blocking message, the error ends with `This hook comes from the <plugin> plugin.` so that you know which plugin to disable or fix. Before v2.1.281, the error didn't name the plugin.

844844

845845If that message shows the plugin's path cut off at a space, apply the [unquoted `${CLAUDE_PLUGIN_ROOT}` fix](#hook-error-notices-in-the-transcript).

846846

847847#### Hook loads but never fires

848848

849If 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:

849If 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.md#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:

850850

851851**1. Check the event name**

852852

from line 862

862862

863863**4. Read the debug log**

864864

865Open the [debug log](/docs/en/hooks#debug-hooks), which records which hooks matched. A hook that ran shows up there with its exit code.

865Open the [debug log](/docs/en/hooks.md#debug-hooks), which records which hooks matched. A hook that ran shows up there with its exit code.

866866

867867### `Plugin directory does not exist: <path>`

868868

from line 884

884884

885885* **`Missing environment variables: <names>`**: set those variables in the shell you start Claude Code from, then start a new session

886886* **`URL is unset or invalid`**: a `${user_config.*}` option that the URL uses isn't set. Run `/plugin configure <plugin>` to set it

887* **`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)

888888

889889#### `Bundled MCP server "<name>" was not started: it needs configuration`

890890

891The 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.

891The plugin includes the server as an [MCPB bundle](/docs/en/plugins/components.md#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.

892892

893Select 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.

893Select 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.md#manage-installed-plugins). The server starts once that reload applies. Before v2.1.285, Claude Code skipped the server without showing this line.

894894

895895#### Server is configured but never connects

896896

from line 912

912912

913913### Language server doesn't start, uses too much memory, or reports wrong diagnostics

914914

915You 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.

915You installed a [code intelligence plugin](/docs/en/plugins/code-intelligence.md) and Claude isn't seeing diagnostics, or the language server is using too much memory or reporting errors that aren't real.

916916

917917#### Language server doesn't start

918918

from line 932

932932

933933## Build a plugin

934934

935You're developing a plugin and loading it with `--plugin-dir` or installing it from a local marketplace. These entries cover the failures you hit while developing a plugin. For the checks to run after each change, see [Test and debug](/docs/en/plugins/create#test-and-debug).

936936

937937Two failures that also reach a plugin's users have their entries under [Plugin installed but not working](#plugin-installed-but-not-working):

938938

from line 947

947947

948948> [!NOTE]

949949>

950> Before v2.1.299, this message could appear at startup on a row labeled with a tag such as `synced[0]`. That row is for a plugin [synced from claude.ai](/docs/en/plugins/loading#synced-plugins). It appeared when another Claude Code session on your machine had updated the plugin moments before and moved its files. To load the plugin, restart Claude Code. To keep the message from appearing for this reason, update to v2.1.299 or later.

950> Before v2.1.299, this message could appear at startup on a row labeled with a tag such as `synced[0]`. That row is for a plugin [synced from claude.ai](/docs/en/plugins/loading.md#synced-plugins). It appeared when another Claude Code session on your machine had updated the plugin moments before and moved its files. To load the plugin, restart Claude Code. To keep the message from appearing for this reason, update to v2.1.299 or later.

951951

952952Paths 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.

953953

from line 967

967967

968968A plugin works from its source directory with `--plugin-dir` but fails after install, with errors about a path such as `../shared-utils`.

969969

970Claude 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).

971971

972972### `${CLAUDE_PLUGIN_ROOT}` shows forward slashes on Windows

973973

from line 975

975975

976976Claude Code runs shell-form hooks through Git Bash on Windows and substitutes the plugin root in the forward-slash Win32 form on purpose. Bash builtins, MSYS tools, and native Windows binaries all accept that form.

977977

978If your script needs backslashes, switch the hook to one of the forms that keep native paths, described under [exec form and shell form](/docs/en/hooks#exec-form-and-shell-form):

978If your script needs backslashes, switch the hook to one of the forms that keep native paths, described under [exec form and shell form](/docs/en/hooks.md#exec-form-and-shell-form):

979979

980980* An exec-form hook, which spawns the process directly with an `args` array

981981* A hook with `"shell": "powershell"`

from line 994

994994

995995Check these causes in order:

996996

997* **The skill sets `disable-model-invocation: true`**: the template skill in [Create your first plugin](/docs/en/plugins/create#create-your-first-plugin) sets it. Remove the line from a skill you want Claude to invoke on its own. [Control who invokes a skill](/docs/en/skills#control-who-invokes-a-skill) covers the field

998* **The description doesn't match how people ask**: work through the checks in [Skill not triggering](/docs/en/skills#skill-not-triggering)

999* **The description is truncated**: when many skills are installed, Claude Code shortens descriptions to fit the listing's character budget, which can strip the keywords Claude needs to match a request. See [Skill descriptions are cut short](/docs/en/skills#skill-descriptions-are-cut-short)

997* **The skill sets `disable-model-invocation: true`**: the template skill in [Create your first plugin](/docs/en/plugins/create.md#create-your-first-plugin) sets it. Remove the line from a skill you want Claude to invoke on its own. [Control who invokes a skill](/docs/en/skills.md#control-who-invokes-a-skill) covers the field

998* **The description doesn't match how people ask**: work through the checks in [Skill not triggering](/docs/en/skills.md#skill-not-triggering)

10001000

10011001To 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.

10021002

from line 1004

10041004

10051005You 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.

10061006

1007Change 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).

10081008

10091009### The `userConfig` dialog never appears

10101010

from line 1028

10281028

10291029If 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.

10301030

1031For 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.

1031For a plugin that ships an [MCPB bundle file](/docs/en/plugins/components.md#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.

10321032

10331033### `claude plugin validate` reports errors

10341034

from line 1047

10471047| `Path contains ".." which could be a path traversal attempt: <path>` | A component path escapes the plugin directory. | Use paths inside the plugin root. |

10481048| `Path is a file; skills entries must be directories containing SKILL.md` | A `skills` entry points at `SKILL.md` instead of its directory. | Point at the parent directory, or `.` for a root-level `SKILL.md`. |

10491049| `No frontmatter block found` or `YAML frontmatter failed to parse: <error>` | A skill, agent, or command file has missing or invalid YAML frontmatter. | Add or fix the frontmatter between `---` delimiters. Reported when validating a plugin directory. |

1050| `Plugin name "<name>" is reserved: it passes as one of Anthropic's own` | The plugin's `name` is one of the [reserved names](/docs/en/plugins/manifest-reference#name). | Rename the plugin for what it does. |

1051| `Unknown field '<key>'` | The manifest has a field the schema doesn't define. | Remove it, or use the name the message suggests. Claude Code ignores unknown fields at load time. For `privacyPolicyUrl` and the other directory listing fields in `plugin.json`, see [Directory listing fields](/docs/en/plugins/manifest-reference#directory-listing-fields). |

1050| `Plugin name "<name>" is reserved: it passes as one of Anthropic's own` | The plugin's `name` is one of the [reserved names](/docs/en/plugins/manifest-reference.md#name). | Rename the plugin for what it does. |

10521052

10531053Run the command again after each fix until it prints no errors.

10541054

1055`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).

1055`plugin.json` fields are on the [manifest reference](/docs/en/plugins/manifest-reference.md), and marketplace-level messages are under [Marketplace validation errors](#marketplace-validation-errors).

10561056

10571057### `Plugin <name> has conflicting manifests`

10581058

10591059The plugin fails to load with `Plugin <name> has conflicting manifests: both plugin.json and marketplace entry specify components.`

10601060

1061The 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).

10621062

10631063### `Warning: No commands found in plugin <name> custom directory`

10641064

from line 1072

10721072

10731073### Plugins with relative paths fail in URL-based marketplaces

10741074

1075Users 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).

1075Users 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.md#marketplace-entry-path-does-not-stay-inside-the-marketplace-directory).

10761076

10771077When a user adds a URL-based marketplace, Claude Code downloads only the `marketplace.json` file itself. It doesn't fetch plugin files by relative path from that server, so a relative path in an entry points at a directory that was never fetched. Give each entry a source Claude Code can fetch on its own, such as a GitHub repository:

10781078

from line 1080

10801080{ "name": "my-plugin", "source": { "source": "github", "repo": "owner/repo" } }

10811081```

10821082

1083Alternatively, 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).

10841084

10851085### Marketplace validation errors

10861086

from line 1109

11091109

11101110## Blocked by your organization

11111111

1112Your 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).

11131113

11141114### `Marketplace source '<source>' is blocked by enterprise policy`

11151115

from line 1163

11631163

11641164An operator pre-populated this marketplace through `CLAUDE_CODE_PLUGIN_SEED_DIR`, and Claude Code treats a seed-managed marketplace as read-only. A bulk `marketplace update` skips it and updates the others.

11651165

1166To change the marketplace's content, ask the person who maintains the seed image to update it. For the procedure, see [Seed containers and CI](/docs/en/plugins/org#seed-containers-and-ci).

1166To change the marketplace's content, ask the person who maintains the seed image to update it. For the procedure, see [Seed containers and CI](/docs/en/plugins/org.md#seed-containers-and-ci).

11671167

11681168## Next steps

11691169

1170* [Plugin loading reference](/docs/en/plugins/loading): why scopes, the cache, and precedence behave the way they do

1171* [Plugin commands reference](/docs/en/plugins/cli-reference): flags, defaults, output, and exit codes for the `claude plugin` commands

1172* [Install and manage plugins](/docs/en/plugins/install): the install steps from the start

1173* [Manage plugins for your organization](/docs/en/plugins/org#troubleshoot-policy): policy-side troubleshooting for administrators

1170* [Plugin loading reference](/docs/en/plugins/loading.md): why scopes, the cache, and precedence behave the way they do

1171* [Plugin commands reference](/docs/en/plugins/cli-reference.md): flags, defaults, output, and exit codes for the `claude plugin` commands

1172* [Install and manage plugins](/docs/en/plugins/install.md): the install steps from the start

1173* [Manage plugins for your organization](/docs/en/plugins/org.md#troubleshoot-policy): policy-side troubleshooting for administrators

11741174

This page’s history 28 edits

21 Oct 2026 +78 −78 · this one
21 Oct 2026 +4 −0
20 Oct 2026 +1 −0
20 Oct 2026 +192 −304
19 Oct 2026 +1 −1
14 Oct 2026 +2 −1

The page’s own history →

Where it came from

The captureclaude-code
Upstream pagecode.claude.com

Around it

Every changethe ledger
That day21 Oct 2026