Plugin troubleshooting

This page is a lookup table for plugin and marketplace errors. Search it for the message you saw (placeholders such as <name> stand in for the plugin or marketplace it mentions). Each entry explains what went wrong and what to do, and most tell you what success looks like so you know the fix worked.

Messages are grouped by the stage that produces them, which is not always the command you ran. An install that fails because the marketplace is missing, for example, is listed under adding a marketplace.

If you want the underlying rules rather than a fix, read How plugins load. For flags and fields, see the plugin CLI reference, the manifest reference and the marketplace reference. Messages mentioning a hooks module come from mods; see Troubleshoot mods.

Typing /plugin in the wrong place

/plugin is something you type inside an interactive Claude Code terminal session. It opens a panel. Most of the confusion in this section comes from typing it somewhere else.

/plugin isn't available in this environment

You typed it in a session with no terminal to draw the panel: claude -p, the Agent SDK, the desktop app's Code tab, the VS Code extension panel, or claude.ai/code. (In the VS Code panel, plain /plugin or /plugins opens a Manage plugins dialog; only /plugin followed by something gets this reply.)

Install through the surface you are on instead:

A terminal install shows ✓ Installed <plugin>. in a session, or Successfully installed plugin: <plugin>@<marketplace> from the shell.

zsh: no such file or directory: /plugin

(Bash says bash: /plugin: No such file or directory.) You typed a session command at your shell prompt. Either start claude and type it there, or use the shell form, claude plugin install <plugin>@<marketplace>.

The term '/plugin' is not recognized as the name of a cmdlet

The PowerShell version of the same mistake. Same fixes.

claude: command not found after claude plugin ...

The shell cannot find Claude Code at all (on Windows: 'claude' is not recognized ...). This is an installation problem, not a plugin one; work through the PATH checks in Troubleshoot installation and retry.

Unknown command and commands that do not exist

Several spellings circulate online that Claude Code has never had:

And some that look wrong but are fine: claude plugins (alias of claude plugin), claude plugin remove (alias of uninstall), and /plugins or /marketplace (aliases of /plugin).

Adding a marketplace

Marketplace "claude-plugins-official" not found

The official marketplace is not registered on this machine. It normally registers itself the first time you start an interactive terminal session, so it may be missing if you have only used the VS Code extension. It is also skipped or deferred when policy blocks it, when CLAUDE_CODE_DISABLE_OFFICIAL_MARKETPLACE_AUTOINSTALL is set, or after a failed attempt that is waiting to retry. The claude plugin shell commands never register it.

/plugin marketplace add anthropics/claude-plugins-official

You should see Successfully added marketplace: claude-plugins-official. The same message in the Errors tab means a plugin in your settings names a marketplace you have not added.

Marketplace "<name>" not found

Two causes:

• /plugin install <plugin>@<name> names a marketplace you have not added. Install lines do not say where a marketplace is hosted and there is no global index, so ask whoever gave you the line for its source (owner/repo, git URL or path), add it, and retry. If you already added it, compare the spelling with /plugin marketplace list.
• /plugin install <source> with a path, URL or owner/repo always gives this error, even for a source you have added. To add and install in one go, use /plugin install <plugin> --marketplace <source> (see Install plugins).

Names starting claudeai- are hosted on claude.ai; add them from the shell with claude plugin marketplace add --claudeai <name>.

Anything someone sends you is third-party; review it before installing.

Invalid marketplace source format

The full text is Invalid marketplace source format. Try: owner/repo, https://..., or ./path. Accepted forms are GitHub owner/repo, an http(s):// URL, a user@host:path SSH address, or a local path starting ./, ../, / or ~. A bare name or bare hostname matches none of them.

'<source>' is not a valid GitHub owner/repo shorthand

You gave something with a slash that is not owner/repo, such as github.com/owner/repo or git.acme.internal/team/plugins. The shorthand is GitHub-only and follows GitHub's naming rules. Use the full clone URL for any host, an https:// URL for a hosted marketplace.json, or a path for a local checkout:

/plugin marketplace add https://git.acme.internal/team/plugins.git

Invalid git URL

Claude Code inspects every git address before calling git, and refuses unsupported protocols and addresses git could interpret as pointing somewhere other than they appear to. The text after the address says what to change. If the message instead says is blocked by enterprise policy, see the policy section.

Path does not exist: <path>

A local path that resolves to nothing. Relative paths are resolved from your current directory, and the message shows the resolved path. Run from the right folder or use an absolute path. Note that a path must be either a folder containing .claude-plugin/marketplace.json or a .json file; any other file gives File path must point to a .json file (marketplace.json).

Marketplace file not found at <path>/.claude-plugin/marketplace.json

The repository or download arrived, but the catalogue is not where expected (reported as Failed to add marketplace: Marketplace file not found at ...). If you own it, move the file to .claude-plugin/marketplace.json at the repository root and re-add. Otherwise ask the owner for the exact source to use.

SSH authentication failed or HTTPS authentication failed

These follow Failed to clone marketplace repository:. First rule out the boring causes: a typo in owner/repo, a repository that does not exist, or a private repository you cannot see. Open the URL in a browser or run git ls-remote <url>.

If the repository is right, it is credentials. Claude Code runs git with prompts disabled, so anything that needs to ask you (a password, a key passphrase) fails; the underlying error may mention Cannot prompt because user interactivity has been disabled or terminal prompts disabled.

• SSH: ssh -T git@<host> must work without a passphrase prompt, and the host must already be in known_hosts.
• HTTPS: your credential helper must already hold a token. For GitHub, gh auth login then gh auth setup-git; elsewhere, store a personal access token in your helper.

When git ls-remote <url> works silently in your terminal, retry. To skip SSH for GitHub shorthand, set CLAUDE_CODE_PLUGIN_PREFER_HTTPS=1; otherwise Claude Code uses SSH when a github.com key seems configured and falls back to HTTPS on failure. Background updates have their own credential behaviour, described on Host a marketplace.

SSH host key is not in your known_hosts file

Clones use StrictHostKeyChecking=yes, so a host you have never connected to is refused rather than trusted automatically. Connect once by hand to accept the fingerprint (for example ssh -T git@gitlab.com), then retry. For a public repository, using the https:// URL avoids SSH entirely. If the message is SSH host key has changed, follow its ssh-keygen -R <host> hint after confirming the change is legitimate.

Command 'git' not found or is in an unsafe location

Windows only. Claude Code needs git on your PATH and will not run one found only in the current directory. Install Git for Windows, open a fresh terminal, confirm git --version works, and retry.

Git clone timed out after 120s

Clones and update re-clones get 120 seconds by default. Raise the limit (in milliseconds) and retry in the same shell:

export CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS=300000

$env:CLAUDE_CODE_PLUGIN_GIT_TIMEOUT_MS = "300000"

For a monorepo, claude plugin marketplace add <source> --sparse <paths> limits the checkout to what you need.

Marketplace updates keep failing when offline

For marketplaces with auto-update on, every session checks the git host in the background. When the host is unreachable, Claude Code tries a fresh clone, which also fails offline. Nothing breaks (the existing checkout stays and start-up is not delayed), but it is noisy. Set:

export CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1

This only skips the re-clone for checkouts that already contain .claude-plugin/marketplace.json, so add the marketplace once while online. For fully offline images, pre-populate a seed directory instead (see Manage plugins for your organisation).

Adding from GitHub Enterprise Server fails

A policy error means your organisation restricts sources and an admin needs a hostPattern for your GHES host. A GitHub access error on claude.ai means your GHES account is not connected yet. Both are covered on GitHub Enterprise Server.

Installing a plugin

Plugin "<name>" not found in marketplace "<marketplace>"

The plugin is not in your local copy of that catalogue. From the shell, the same text also appears if you have not added the marketplace at all; if claude plugin marketplace update <marketplace> then says Marketplace '<marketplace>' not found, add it first.

With a refresh hint (Your local copy may be out of date, suggesting claude plugin marketplace update <marketplace>, or The marketplace couldn't be refreshed (...)): the catalogue was not refreshed before lookup, perhaps because you are offline. Refresh with /plugin marketplace update <marketplace> and retry. How plugins load lists when the pre-install refresh is skipped.

With no hint: the name is probably wrong. Copy it from Discover in /plugin. (Before v2.1.232, the named marketplace was only refreshed after a miss and only if it auto-updated.)

Plugin "<name>" not found in any marketplace

(From the shell: ... not found in any configured marketplace.) You omitted @marketplace. Without it, claude plugin install searches cached catalogues without refreshing, and /plugin install only refreshes auto-updating ones. Name the marketplace so it gets refreshed first. If you do not know which one has the plugin, check /plugin marketplace list and browse Discover.

Plugin '<name>@<marketplace>' is already installed globally

It is already installed at user scope or by managed settings, so it is available everywhere (the word globally is omitted if you typed just the name). Manage it from Installed in /plugin. A plugin installed only at project or local scope does not trigger this; you may add a user-scope install too. From the shell, an existing install at the target scope reports already installed (scope: user) and exits 0, re-downloading if the cache folder is missing.

"<plugin>" was not installed: it would share its folder with "<other>"

(Or would share its saved data with.) Two plugin ids map to the same folder on disk once . and @ become -, and on macOS and Windows ids that differ only in case also collide. Installing both would mix their files, so the new one is refused. If the other plugin is installed, the message gives the uninstall command; run it and retry. If both ids arrive in one install (a plugin and its dependency, say), only a marketplace maintainer can fix it by renaming one.

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

The entry uses a newer source type. Update Claude Code and retry.

Plugin archive integrity check failed

An archive entry pins a sha256 and the downloaded zip does not match; the message shows both digests and confirms nothing was installed.

• Publisher: recompute the digest of the exact file served (shasum -a 256 file.zip, or Get-FileHash -Algorithm SHA256 file.zip) and update the entry.
• Installer: run /plugin marketplace update <name> in case the entry was fixed, then retry. If it still disagrees, ask the owner which file they pinned before going further.

An npm plugin source must name a registry package

An npm entry's package value was refused before anything was fetched; the message names the value and the reason (a github: spec, for instance). The marketplace owner must change it to a registry name, name@version or tarball link, or switch to a github, url or git-subdir source.

Marketplace "<name>" is registered from an untrusted source

The marketplace uses a name reserved for official Anthropic marketplaces but was not registered from a github.com/anthropics/ repository. Reserved names are re-checked on every load, so it and its plugins stop loading. Users: claude plugin marketplace remove <name> and re-add from the official repository. Third-party publishers whose name later became reserved: rename and ask users to re-add. (Before v2.1.205, the name was only checked when adding.)

Marketplace "<name>" is added but ignored

The marketplace's record in ~/.claude/plugins/known_marketplaces.json failed a check that runs every time the file is read, so neither it nor its plugins load. claude plugin list prints a line explaining why and what to do; the Errors tab shows the same split across two lines. The reason tells you which check failed:

Fixes: remove it with claude plugin marketplace remove <name> (which works on ignored entries and uninstalls its plugins), re-add from a supported source or a local copy, and reinstall. To keep a marketplace on a network share, declare it in extraKnownMarketplaces in user or managed settings (project settings do not count). For a mismatch, re-add from the declared source or change the declaration. A refused name will be refused again if re-added unchanged. Versions before v2.1.286 reported these as not found or registered but was refused.

Plugin <name> has a corrupt manifest file / has an invalid manifest file

The plugin downloaded, but its .claude-plugin/plugin.json is unreadable. corrupt plus JSON parse error: means bad JSON; invalid plus Validation errors: means it parses but breaks the schema (for example name: Invalid input). From the shell the <name> may be a temp folder, but the Failed to install plugin "<name>@<marketplace>" prefix shows the real one, and the exit code is 1. Authors: run claude plugin validate on the plugin folder. Everyone else: report it to the marketplace owner.

Plugin directory not found at path: <path>

An enabled relative-path plugin's folder is missing from the marketplace. The maintainer must fix the entry's source or restore the folder. Marketplace directory not found at path: <path> instead means the whole locally added marketplace moved or was deleted; restore it, or remove and re-add from its new location.

No plugins available / No marketplaces configured

Nothing is registered, so there is nothing to browse. Add the official marketplace with /plugin marketplace add anthropics/claude-plugins-official; Anthropic marketplaces lists others.

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

You used /plugin install <plugin> --marketplace <source>, and the catalogue at that source has the same name as one you already registered elsewhere. The existing one is kept and nothing is installed. Install from the existing one with /plugin install <plugin>@<name>, or remove it with /plugin marketplace remove <name> and retry.

Cannot add marketplace "<name>": its source doesn't match its extraKnownMarketplaces entry in user or managed settings

Your user or managed settings already declare a marketplace with that name, from a different source. Sources match only if type and every field are identical, so a declared ref you did not pass counts as different, as does giving an https://github.com/ URL for a github declaration (URLs are recorded as git sources).

Declared marketplaces register themselves, so first check /plugin marketplace list; it may already be there. If not, add it exactly as declared; for { "source": "github", "repo": "acme/claude-plugins", "ref": "v3" } that is /plugin marketplace add acme/claude-plugins#v3. To use a different source, change or remove the declaration (or ask your admin, if it is managed). Before v2.1.287 the wording was different but meant the same.

Failed to install: <plugin> (<reason>)

A multi-select install from the /plugin menu failed for every plugin. Long reasons (git output, say) are cut to the first line, and the summary then suggests installing from the plugin's details. Fix what the reason names, or select the plugin in Discover and press Enter to see the full error.

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

Installs download a fresh copy and move it into the cache version folder. The move failed, usually because something else (a virus scanner, an editor, another Claude Code session) was using the folder; the error code in parentheses (for example ENOTEMPTY) gives detail. Read the message for the state of your previous copy:

• The previously installed copy was moved back: you still have the old version.
• had to be removed first, was not moved back or could not be moved back: that version is not installed until a retry succeeds.
• No such sentence: there was no previous copy.
• On Windows, could not be replaced with It was not replaced and the new copy was discarded: the old version is intact.

Any Left on disk folders are cleaned up later automatically. Close whatever is using the folder under ~/.claude/plugins/cache and retry; if told to, fix permissions and free disk space first.

Dependency errors

These appear either as an install error or, at load time, in claude plugin list and the Errors tab, where the affected plugin stays disabled until resolved. Authoring rules are on Plugin dependencies.

claude plugin list --json exposes these in errors, with errorDetails[].type of dependency-unsatisfied (first two rows) or dependency-version-unsatisfied (third).

Installed, but not working

Start here: the plugin or its skills do not show up

1. Open /plugin > Installed and check the plugin is there and enabled (claude plugin list shows the same, with Status: ✔ enabled).
2. Open the Errors tab. Each entry pairs a message with guidance, and most messages below come from there.
3. If you installed during this session and see no errors, run /reload-plugins. It prints a Reloaded: summary and, on failures, N errors during load. Run /plugin for details.

Still nothing? For your own plugin, see skills missing. For someone else's, open its details in Installed: if it lists no skills, it has none to offer.

Run /reload-plugins to apply.

The install summary ended with this instead of Plugin is now active., possibly with Plugins changed. Run /reload-plugins to activate. above the prompt. Activation was deferred because it would invalidate the prompt cache, or because it failed. You do not have to type anything: when the panel closes, the reload runs (or queues until the current response finishes). Read its output:

• A Reloaded: summary means it is active.
• A line starting This reload changes MCP tools (...), warning that your next message will re-read the whole conversation and telling you to run /reload-plugins --force (or a variant starting This reload adds the LSP tool or This reload removes the LSP tool), means you choose: rerun with --force, or start a new session. Prompt caching explains the trade-off.

The packages it lists are not installed / were not installed, because ...

The plugin's Node.js dependency install left no node_modules, so parts of it may fail.

• are not installed: the install could run but did not finish. Retry with the claude plugin update <plugin>@<marketplace> command the note gives, or update from /plugin. With CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC set, the retry is skipped.
• were not installed, because ...: the install cannot run for this plugin, for a stated reason such as a Yarn, pnpm or bun.lockb lockfile, or a missing package manager. Updating will not help until the reason is fixed: the author must change the lockfile, or you must install the package manager.

Plugin "<name>" not cached at <path>

An install record exists but its folder is gone (perhaps you cleared the cache). claude plugin install <name>@<marketplace> re-downloads it, then /reload-plugins.

installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read

A record parses as JSON under a valid id but its fields do not make sense to this version, almost always because a newer Claude Code wrote it. It appears as a Note: in claude plugin list, and install, uninstall and update refuse with was not installed: (and so on) plus this text, or failureCode: "install_records_unreadable" in JSON. With several records it says holds records under; if the whole file declares an unknown format, it says installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know.

This version will not rewrite the file while that record exists, so nothing is lost. In order: run claude update; failing that, uninstall the plugin with whichever version wrote it; as a last resort, delete the record by hand and restart or /reload-plugins.

installed_plugins.json could not be read and was rebuilt

The file was not valid JSON or not a plugin list, so it was rebuilt and the old one kept as installed_plugins.unreadable.<date>.<hash>.kept. Open the .kept file to see what you had, and reinstall anything missing. It is never read back and ages out on the cleanupPeriodDays schedule.

install records under names that no version of Claude Code can use were removed from installed_plugins.json

Some records sat under keys that are not valid plugin ids. They were copied to installed_plugins.set-aside.<date>.<hash>.json and dropped; everything else loads. As the note says, nothing needs doing.

Disabled in ~/.claude/settings.json but still loads

A higher-precedence settings source enables the plugin, and the message names it (for example, that project settings enable it, which overrides your user setting). To opt out of a project-enabled plugin just for you, set it false in .claude/settings.local.json. If the plugin is instead marked required by your org, it is a synced plugin your organisation requires on claude.ai, and no settings file can override it. Precedence is laid out on How plugins load.

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

Repository settings can switch a plugin on but cannot download one from an external source. Run the command from the guidance line, claude plugin install <name>@<marketplace> --scope project, then /reload-plugins. Organisation-wide pre-installs go through managed settings instead (org guide).

Plugin hooks fail to load, error, block, or never fire

Fail to load (in Errors):

• Failed to load hooks from <path>: <reason>: hooks/hooks.json is invalid JSON or fails the schema. Fix it; claude plugin validate catches JSON problems before you publish.
• hooks path not found: <path>: the manifest's hooks points at a missing file.

<Event> hook error: Failed with non-blocking status code: <stderr> in the transcript means the hook ran and its command failed. /bin/sh: node: command not found, for instance, means node is not on the PATH Claude Code inherited from the terminal you launched it in. If the stderr shows the plugin path cut off at a space, a shell-form command uses ${CLAUDE_PLUGIN_ROOT} without quotes; wrap it in double quotes or switch to exec form (the validator warns about this). For anything else, run the command by hand from the plugin folder or capture stderr with hook debug logging (Hooks).

A hook blocks something: an exit code of 2 blocks the action. When it is a plugin hook, the error ends This hook comes from the <plugin> plugin. so you know what to disable (from v2.1.281).

Loads but never fires: check the event name's exact casing (PostToolUse, not postToolUse), check the matcher matches the tool name, trigger the event deliberately, then read the debug log, which records which hooks matched and their exit codes.

Plugin MCP servers that fail or never connect

Invalid MCP server config for "<server>": <error>, by the text after the colon:

• Missing environment variables: <names>: set them in the shell you launch from and start a new session.
• URL is unset or invalid: a ${user_config.*} value the URL uses is empty; run /plugin configure <plugin>.
• has an invalid MCP url, or headersHelper for MCP server '<server>' references ${user_config.*}: a bug in the plugin's own config (the latter is explained on Errors). Fix it or report it.

Bundled MCP server "<name>" was not started: it needs configuration: an MCPB bundle declares user_config and a required value is missing or invalid. The rest of the plugin works. Use Configure on the plugin in Installed; after Configuration saved. the panel closes, plugins reload, and the server starts.

Configured but never connects: check /mcp. For the server's own start-up error, run claude --debug and read ~/.claude/debug/<session-id>.txt (the flag writes there, not to the terminal). A .mcp.json entry that fails the schema never reaches Errors; it is dropped and logged as Invalid MCP server config for <server> in <path> in the debug log only. claude plugin validate reports it from v2.1.281.

Works with --plugin-dir, fails once installed: installed plugins run from the cache, so paths that only work from your source folder break. Use ${CLAUDE_PLUGIN_ROOT} for everything inside the plugin.

Language server problems

For code intelligence plugins:

• Will not start. The binary is installed separately and found via PATH. Errors shows something like Executable not found in $PATH: "<binary>", and --debug logs LSP server <name> failed to start: <reason>. Install it, check with which, and start a new session.
• Too much memory. Servers like rust-analyzer and pyright index the whole project. Disable the plugin with /plugin disable <plugin> and lean on Claude's built-in search.
• Bogus diagnostics in a monorepo. An unconfigured server may not resolve internal packages. Nothing to fix in Claude Code, and it does not stop edits.

Building a plugin

Two problems that also affect users (hooks that do not fire, MCP servers that do not start) are covered in the previous section. Create a plugin has the routine checks to run after each change.

commands path not found: <path>

(Also for skills, agents and hooks.) A manifest or entry path resolved to nothing; the message shows the absolute path checked. Paths are relative to the plugin root and start ./. Fix and /reload-plugins. A path escaping the root is reported as <component> path escapes plugin directory instead.

--plugin-dir pointed at a marketplace loads nothing

--plugin-dir wants a plugin root (the folder with .claude-plugin/plugin.json). Given a marketplace root, it does not read marketplace.json, so nothing under plugins/ loads and there is no error. Point it at the plugin: claude --plugin-dir ./my-marketplace/plugins/my-plugin. (Before v2.1.281, a marketplace root loaded as one empty plugin.)

Files outside the plugin folder are not found

Works from source, fails after install, with errors about paths like ../shared. Installed plugins are copied into the cache without anything outside their folder. Move shared files inside, or use a symlink within the plugin (see How plugins load for the symlink rules).

${CLAUDE_PLUGIN_ROOT} has forward slashes on Windows

Deliberate. Shell-form hooks run through Git Bash on Windows and get the forward-slash Win32 form (C:/Users/...), which Bash, MSYS tools and native binaries all accept. If a script insists on backslashes, use an exec-form hook or set "shell": "powershell" (see Hooks).

Plugin loads but its skills are missing

Skills belong in skills/ and commands in commands/ at the plugin root. Only plugin.json goes inside .claude-plugin/; a skills/ folder in there is never scanned. Each skill is a folder containing SKILL.md; a manifest skills entry pointing at the file itself gives path is a file; skills entries must be directories containing SKILL.md. Move things and /reload-plugins.

Skill works when typed, but Claude never uses it

In order of likelihood:

1. The skill has disable-model-invocation: true (the starter template sets it). Remove it if Claude should invoke the skill on its own.
2. The description does not match how people phrase requests.
3. With many skills installed, descriptions are shortened to fit a budget and the useful keywords got cut.

Skills covers all three. To measure trigger rate properly, write an eval case with a tool_used: Skill grader and run claude plugin eval after each change (see Plugin evals).

<directory> is not a plugin or skill folder from claude plugin eval init

You ran it outside a plugin root, so it stopped rather than create an evals/ folder the plugin would never see. cd to the folder with .claude-plugin/plugin.json or the skill's SKILL.md, or pass --eval-dir.

The userConfig dialog never appears

It depends where you install:

• /plugin install or Discover: the dialog is part of the flow.
• VS Code's Manage plugins dialog: shows a form for unset options after install (from v2.1.285; earlier, use /plugin configure <plugin>@<marketplace> in a terminal session).
• claude plugin install: never prompts. Pass --config key=value per option. Unset options produce a line beginning N userConfig options not yet set (with (M required) if any are required) that points you to /plugin configure <plugin>@<marketplace> or --config KEY=VALUE.

Afterwards you can set values with /plugin configure in a session or claude plugin configure from the shell. An undeclared --config key still installs the plugin but prints ⚠ Installed, but --config not applied: ... listing the valid keys. For plugins shipping an MCPB bundle with its own user_config, those keys appear as <server>.<key>; a bundle referenced by URL is not read at install, so configure it in /plugin.

claude plugin validate reports errors

It prints Found N errors and Validation failed, exit 1. For marketplaces, problems inside an entry's own manifest are prefixed like plugins[1] plugin.json → json: .... The messages that fail a run (plus two warnings that only fail under --strict):

Rerun after each fix until clean.

Plugin <name> has conflicting manifests

The plugin has a plugin.json, and its marketplace entry has strict: false while also declaring commands, agents, skills, hooks, outputStyles or themes. Remove those from the entry, or set strict: true so they are appended. See the marketplace reference.

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

Only visible in the --debug log. The manifest's commands folder exists but has no .md files and no SKILL.md subfolders. Add them or remove the path.

Hosting a marketplace

Relative paths fail for URL-hosted marketplaces

Users who added your marketplace as a marketplace.json URL get its marketplace entry path does not stay inside the marketplace directory on install, or Plugin source path refused for already-installed plugins. Only the catalogue file is downloaded, so relative paths point at nothing. Give each entry a self-contained source (such as { "source": "github", "repo": "acme/pdf-tools" }), or host in git so the whole tree is cloned. Errors has the reference entry.

Marketplace validation errors

claude plugin validate . also checks each local-path entry and warns about version disagreements. Marketplace-level messages:

The full list is on the marketplace reference.

Blocked by your organisation

Your organisation's managed settings refused something. Each entry names the setting so you know what to ask your administrator. The admin view is Manage plugins for your organisation.

Marketplace source '<source>' is blocked by enterprise policy

blockedMarketplaces or strictKnownMarketplaces does not permit the source (for git sources the host follows in parentheses). The rest of the message tells you which:

• Allowed sources: <list>: the allowlist. Use one of those, or ask for yours to be added.
• No external marketplaces are allowed.: the allowlist is empty.
• A Tip: about shorthand assuming github.com: the allowlist permits your internal host by name, but owner/repo points at GitHub. Use the full URL, such as git@git.acme.internal:team/plugins.git.

Marketplaces you added before a tighter policy arrived also stop refreshing.

Marketplace "<name>" is not in the allowed marketplace list

Or ... is blocked by enterprise policy, in Errors for an already-registered marketplace. The same policies apply at load, so it and its plugins stop. Guidance shows the allowed sources, Contact your administrator to configure allowed marketplace sources, or This marketplace source is explicitly blocked by your administrator.

Plugin "<name>" is blocked by your organization's policy and cannot be installed

(Or cannot be enabled, or variants naming a blocked marketplace or a blocked dependency.) Managed settings block the plugin, its marketplace or a dependency. A blocked dependency means the plugin cannot install until that dependency's marketplace is allowed.

--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)

Also for --plugin-url, --agents and --mcp-config, followed by a line about approved sources. Use an approved marketplace or ask for the setting to change. A related Errors entry, --plugin-dir copy of "<name>" ignored: plugin is locked by managed settings, means policy pins that plugin name so your local copy cannot override it.

Plugins from ~/.claude/skills/ are blocked by your organization's managed settings

From claude plugin init or enable. The allowlist lacks {"source":"skills-dir"}, or the blocklist includes it. Ask your admin to make the change the message names.

Command-sourced plugins are disabled by your organization's managed settings

disableCommandPluginSources is set (or allowManagedHooksOnly is set and the former is unset), so command sources cannot install or update and their commands never run. Ask whether the plugin can be published with another source type.

Marketplace '<name>' is seed-managed

This marketplace comes from CLAUDE_CODE_PLUGIN_SEED_DIR and is read-only; bulk updates skip it. Ask whoever maintains the image to update the seed.

Related

• How plugins load
• Plugin CLI reference
• Install plugins
• Manage plugins for your organisation
• Errors