# Claude Code Plugin Not Installing or Not Loading? 12 Causes and Fixes > **Want a plugin that's known to install?** Our free [Solo Consultant Skills plugin](https://solostackkits.netlify.app/plugins/) is a one-plugin marketplace hosted as a plain `marketplace.json` URL with a checksum-pinned zip. No GitHub account needed. It makes a good test: if it installs and the one you want doesn't, the problem is in that plugin's marketplace, not your setup. You ran an install line from a README and got an error, or the install said it worked and nothing new appeared when you typed `/`. Plugin problems happen at three different stages: adding the marketplace, installing the plugin, and loading it into the running session. The fix depends on which stage failed, so find the stage first. ## First: which stage failed? Run `/plugin` in a Claude Code terminal session and check two tabs. **Installed** lists every plugin with its scope and whether it's enabled. **Errors** lists load failures, each with a guidance line. From your shell, `claude plugin list` prints the same list with `Version`, `Scope` and `Status` lines. - Not listed at all: the install failed. Start at cause 1. - Listed and enabled, but its skills don't show up: go to cause 7. - Listed with an error: match the message under causes 7 to 12. ## The marketplace won't add or can't be found: 4 causes 1. **You typed `/plugin` in the wrong place.** `/plugin` only runs inside an interactive Claude Code terminal session. Typed at a shell prompt, zsh reports `no such file or directory: /plugin`. In `claude -p`, the Agent SDK, the desktop app's Code tab or claude.ai/code, Claude replies `/plugin isn't available in this environment.` From a shell, use the shell form instead: `claude plugin install @`. In VS Code, type `/plugins` to open **Manage plugins**. Cloud sessions don't load plugins installed on your own machine. 2. **You used a command spelling that doesn't exist.** `claude plugin add ` fails with `error: unknown command 'add'`, `--project` fails with `error: unknown option '--project'`, and `/install` isn't a command. The real forms are `claude plugin marketplace add ` to add a catalog, `claude plugin install @ --scope project` to install for the repo, and `/plugin install @` in a session. 3. **The marketplace was never added.** An install line like `formatter@acme-tools` names a marketplace, but not where it's hosted, and Claude Code has no index to look the name up in, so you get `Marketplace "acme-tools" not found`. Add the source first: `/plugin marketplace add owner/repo` for GitHub, the full `https://...git` clone URL for another git host, a `./path` for a local folder, or the `https://` URL of a hosted `marketplace.json`. If even the official one is missing, run `/plugin marketplace add anthropics/claude-plugins-official`. 4. **The source is in a form Claude Code won't read.** A bare name or hostname gives `Invalid marketplace source format`, and `github.com/owner/repo` or a `gitlab.example.com/group/project` path without `https://` is rejected as not a valid GitHub `owner/repo` shorthand. Start a relative path with `./`, because `name/name` is read as GitHub. Private repos clone with your existing git credentials and never prompt, so `SSH authentication failed` or `HTTPS authentication failed` usually means `git ls-remote ` doesn't work from your terminal either; fix that first (for GitHub, `gh auth login` and `gh auth setup-git`). ## The install itself fails: 2 causes 5. **The plugin name doesn't match the catalog.** `Plugin "" not found in marketplace ""` means your local copy of the catalog has no entry by that name. If the message carries a refresh hint, refresh with `/plugin marketplace update ` and retry. With no hint, the name is wrong: open **Discover** in `/plugin` and copy it. Always install as `name@marketplace`. A bare `claude plugin install ` reads only the catalogs already on disk and doesn't refresh them first. 6. **The download fails a check.** For a plugin shipped as a zip, `Plugin archive integrity check failed` means the file's SHA-256 doesn't match the `sha256` pin in the marketplace entry, and Claude Code refuses it on purpose. Refresh the marketplace, and if it still fails, ask the publisher. `This plugin uses a source type your Claude Code version does not support` means you need to update Claude Code. ## Installed, but nothing shows up: 4 causes 7. **It isn't loaded in this session yet.** Installing writes to disk, but the running session only picks up plugins at startup or on `/reload-plugins`. If the install summary ends with `Run /reload-plugins to apply.` instead of `Plugin is now active.`, the reload was held back, often because adding a plugin MCP server would invalidate your prompt cache. In that case run `/reload-plugins --force` or start a new session. A successful reload prints `Reloaded:` with counts of plugins, skills, agents, hooks and servers. 8. **You're typing the wrong name.** Plugin skills are always namespaced: `/:`, as in `/solo-consultant-skills:invoice-chase`, never plain `/invoice-chase`. Open the plugin's details on the **Installed** tab to see what it contains. A plugin that lists no skills there has none to show. 9. **The project enables it, but it was never installed here.** A plugin listed under `enabledPlugins` in a committed `.claude/settings.json` is switched on for everyone, but if it comes from an external source such as GitHub, Claude Code doesn't download it for you. The **Errors** tab shows `Plugin "" is enabled in project settings but isn't installed here`. Run `claude plugin install @ --scope project`, then `/reload-plugins`. Project plugins and marketplaces listed under `extraKnownMarketplaces` also wait for you to accept the folder's workspace trust dialog. Trusting a parent folder or running `-p` doesn't count, and cloud sessions never show that dialog. 10. **Another setting turns it off.** `enabledPlugins` can be set in user, project, local, `--settings` and managed settings, and the highest-precedence source that mentions the plugin wins (local beats project, project beats user, and managed beats everything). A `false` in `.claude/settings.local.json` silently disables a plugin the project enabled. If the plugin was set by its author with `defaultEnabled: false`, it installs turned off until you run `claude plugin enable `. Our [settings precedence checker](https://solostackkits.netlify.app/tools/settings-precedence-checker.html) shows which file wins for a key. ## Only some parts work, or it broke after a change: 2 causes 11. **The cache doesn't match the record.** Installed plugins are copied into `~/.claude/plugins/cache////` and load from there. If you cleared that folder, the **Errors** tab shows `Plugin "" not cached at `. Fix it with `claude plugin install @`, which re-downloads a missing copy, then `/reload-plugins`. If an update "does nothing", the plugin's manifest probably pins a `version`, and `claude plugin update` won't replace a cached copy whose computed version is unchanged. Third-party marketplaces don't auto-update by default; turn it on per marketplace from the **Marketplaces** tab. 12. **A hook or MCP server inside it fails.** The plugin loads, but one component is broken. `Failed to load hooks from ` means its `hooks/hooks.json` is invalid. `Invalid MCP server config for "": Missing environment variables` means you need to set those variables in the shell you start Claude Code from. `Bundled MCP server "" was not started: it needs configuration` means you need to choose **Configure** on the plugin's details. Then check `/mcp`, and start `claude --debug` to read the server's startup error in `~/.claude/debug/.txt`. Our [hooks not working](https://solostackkits.netlify.app/blog/claude-code-hooks-not-working.html) and [MCP server not connecting](https://solostackkits.netlify.app/blog/claude-code-mcp-server-not-connecting.html) guides cover those components in depth. ## If you publish the marketplace: 4 marketplace.json mistakes - **Relative paths in a URL-hosted catalog.** When users add `https://example.com/marketplace.json`, Claude Code downloads only that file, so a `"source": "./plugins/my-plugin"` entry fails with `its marketplace entry path does not stay inside the marketplace directory`. Give each entry a fetchable source: `github`, `url`, `git-subdir`, `npm`, or an `archive` zip with a `sha256` pin (which is how our [plugin marketplace](https://solostackkits.netlify.app/plugins/) works). - **Paths written from the wrong folder.** Relative sources start at the marketplace root, the folder that contains `.claude-plugin/`, never inside it. A `..` fails validation, and a missing folder fails at install with `Source path does not exist: `. - **Entry name and manifest name differ.** The entry `name` in `marketplace.json` is the install id, and the `name` in `plugin.json` is the skill prefix. Keep them identical, or people who install by the manifest name get `not found in marketplace`. - **Folders inside `.claude-plugin/`.** Only `plugin.json` belongs there. A `skills/` folder inside it isn't scanned, so the plugin installs with no skills. Put `skills/`, `commands/`, `agents/` and `hooks/` at the plugin root, and write paths inside the plugin with `${CLAUDE_PLUGIN_ROOT}`, because installed plugins run from the cache, not your source folder. Run `claude plugin validate .` in the marketplace folder after every edit. It catches JSON errors, missing `name`/`owner`/`plugins` fields, `..` paths and bad names, but not a remote source that's wrong. Only a real install from your own machine catches that. To test a plugin without installing it, start `claude --plugin-dir ./my-plugin`. Point it at the plugin folder itself, not the marketplace root, or nothing loads and you see no error. If your plugin's skills install but don't appear in `/`, our [slash command not showing](https://solostackkits.netlify.app/blog/claude-code-slash-command-not-showing.html) checklist and free [SKILL.md validator](https://solostackkits.netlify.app/tools/skill-md-validator.html) cover the `SKILL.md` side. Installing a plugin inside a GitHub Actions workflow? The `plugins` input needs `plugin-name@marketplace-name` plus `plugin_marketplaces`; see cause 13 of [Claude Code GitHub Action not working](https://solostackkits.netlify.app/blog/claude-code-github-actions-not-working.html). --- Facts on this page come from Anthropic's Claude Code docs on [installing plugins](https://code.claude.com/docs/en/plugins/install), [troubleshooting plugins](https://code.claude.com/docs/en/plugins/troubleshooting), the [plugin loading reference](https://code.claude.com/docs/en/plugins/loading), the [plugin commands reference](https://code.claude.com/docs/en/plugins/cli-reference), [creating a marketplace](https://code.claude.com/docs/en/plugin-marketplaces), [plugin security](https://code.claude.com/docs/en/plugins/security) and the [settings reference](https://code.claude.com/docs/en/settings-reference). This guide isn't affiliated with Anthropic. Want a tested starting point? Our [Claude Code Power Config Pack](https://solostackkits.gumroad.com/l/claude-code-config-pack/LAUNCH50?utm_source=hashnode&utm_medium=article&utm_campaign=ssk_hashnode_plugin) has 6 lean CLAUDE.md templates, permission presets and 8 tested safety hooks, $6 with the launch code while it lasts. Not ready to buy? Our [free safety hooks](https://solostackkits.gumroad.com/l/claude-code-free-safety-hooks?utm_source=hashnode&utm_medium=article&utm_campaign=ssk_hashnode_plugin) block risky commands before they run.