Troubleshoot plugins changedplugins/troubleshooting
Nearest release: v2.1.296, published 2 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 9 Oct 2026 19:26 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 9 Oct 2026 19:37 UTC.
Upstream edited
Recorded here
Lines+53added
Lines−1removed
From line
229
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits20to this page, all time
The whole hunk
from line 229, old and new numbered
/
from line 229
229229* **You own the marketplace**: put the file at that location and re-add the marketplace
230230* **Someone else hosts it**: ask the owner for the exact source they publish
231231
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>
235
236You 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.
237
238The rest of the message states the rule for the name. In this example, `_internal` breaks the rule by starting with `_`:
239
240```text theme={null}
241Cannot add marketplace "_internal": Claude Code cannot install plugins from a marketplace with this name. Each part of a plugin id (plugin@marketplace) may use only the letters a-z and A-Z, digits, ".", "_" and "-", and must start with a letter or digit. The name is set by "name" in the marketplace's marketplace.json; ask its maintainer to change it.
242```
243
244Give the marketplace a name that fits that rule, then add it again:
245
246* **You own the marketplace**: change `name` in `marketplace.json`, for example to `internal-tools`
247* **Someone else hosts it**: ask the owner to change the name
248
249Before v2.1.295, Claude Code reported the add in this example as successful.
250
232251<h3 id="ssh-authentication-failed-or-https-authentication-failed">
233252 `SSH authentication failed` or `HTTPS authentication failed`
234253</h3>
from line 793
774793
775794Claude 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.
776795
796<h3 id="does-not-load-so-claude-code-ignores-the-whole-file">
797 `does not load (...), so Claude Code ignores the whole file`
798</h3>
799
800The 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.
801
802Fix 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.
803
804The warning follows the success line of `claude plugin install`, `enable`, `disable`, or `claude plugin marketplace add` in your shell:
805
806```text theme={null}
807⚠ /home/user/.claude/settings.json does not load (its "permissions" is not valid), so Claude Code ignores the whole file, including anything this command wrote there. Fix the file, then run this command again if its change is missing. If a newer Claude Code wrote the file, update Claude Code instead.
808```
809
810The text in parentheses names the error:
811
812* **`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`.
813* **`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.
814
777815<h3 id="a-plugin-you-disabled-still-loads">
778816 `Disabled in ~/.claude/settings.json but still loads`
779817</h3>
from line 875
837875
838876If 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).
839877
878If the notice reads `Failed to run: Plugin directory does not exist: <path>`, see [`Plugin directory does not exist`](#plugin-directory-does-not-exist).
879
840880For 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).
841881
842882#### A plugin hook blocks a tool call or prompt
from line 907
867907 </Step>
868908</Steps>
869909
910<h3 id="plugin-directory-does-not-exist">
911 `Plugin directory does not exist: <path>`
912</h3>
913
914Run `/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.
915
916The reload loads the plugin's hooks from its current directory. The failure is shown once per session for each hook event and command, so the hook going quiet doesn't confirm the fix. Read the reload's output instead:
917
918* **`Reloaded:` with no errors line**: the plugin's hooks no longer point at the missing directory
919* **`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
920* **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
921
870922<h3 id="invalid-mcp-server-config-for-and-mcp-servers-that-dont-start">
871923 `Invalid MCP server config for "<server>"` and MCP servers that don't start
872924</h3>
from line 1097
10451097
10461098You 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.
10471099
1048The validator reads the manifest at the path you give it: `.claude-plugin/plugin.json` for a plugin directory, or `.claude-plugin/marketplace.json` for a marketplace directory. For a marketplace, it prefixes problems in an entry's own manifest with the entry index, as `plugins[1] plugin.json → json: ...`.
1100The validator reads the manifest at the path you give it: `.claude-plugin/plugin.json` for a plugin directory, `.claude-plugin/marketplace.json` for a marketplace directory, or both for a directory that holds both. For a marketplace, it prefixes problems in an entry's own manifest with the entry index, as `plugins[1] plugin.json → json: ...`. Before v2.1.289, Claude Code validated a directory that holds both as a marketplace alone.
10491101
10501102The table covers the messages that stop validation and two warnings, `No frontmatter block found` and `Unknown field '<key>'`, which stop it only when you pass `--strict`. Other warnings, such as a missing description, aren't listed.
10511103
No line in this hunk matches that.