← Blog · 2026-10-22

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

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 <plugin>@<marketplace>. In VS Code, type /plugins to open Manage plugins. Cloud sessions don't load plugins installed on your own machine.
You used a command spelling that doesn't exist. claude plugin add <source> 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 <source> to add a catalog, claude plugin install <plugin>@<marketplace> --scope project to install for the repo, and /plugin install <plugin>@<marketplace> in a session.
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.
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 <url> 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

The plugin name doesn't match the catalog. Plugin "<name>" not found in marketplace "<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 <marketplace> 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 <name> reads only the catalogs already on disk and doesn't refresh them first.
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

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.
You're typing the wrong name. Plugin skills are always namespaced: /<plugin>:<skill>, 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.
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 "<name>" is enabled in project settings but isn't installed here. Run claude plugin install <name>@<marketplace> --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.
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 <name>. Our settings precedence checker shows which file wins for a key.

Only some parts work, or it broke after a change: 2 causes

The cache doesn't match the record. Installed plugins are copied into ~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/ and load from there. If you cleared that folder, the Errors tab shows Plugin "<name>" not cached at <path>. Fix it with claude plugin install <name>@<marketplace>, 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.
A hook or MCP server inside it fails. The plugin loads, but one component is broken. Failed to load hooks from <path> means its hooks/hooks.json is invalid. Invalid MCP server config for "<server>": Missing environment variables means you need to set those variables in the shell you start Claude Code from. Bundled MCP server "<name>" 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/<session-id>.txt. Our hooks not working and MCP server not connecting 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 /plugins/ marketplace 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: <path>.
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 checklist and free SKILL.md validator cover the SKILL.md side.

Facts on this page come from Anthropic's Claude Code docs on installing plugins, troubleshooting plugins, the plugin loading reference, the plugin commands reference, creating a marketplace, plugin security and the settings reference. This guide isn't affiliated with Anthropic.