Troubleshoot plugins changedplugins/troubleshooting
Nearest release: v2.1.285, published 9 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 30 Sep 2026 03:24 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 30 Sep 2026 03:37 UTC.
Upstream edited
Recorded here
Lines+45added
Lines−1removed
From line
634
where the diff opens
First seen
25 Sep 2026
this site's first read of the page
Recorded edits29to this page, all time
The whole hunk
from line 634, old and new numbered
/
from line 634
634634
635635Then run `/reload-plugins` in your session. The **Errors** tab entry disappears and the plugin is back under **Installed**.
636636
637<h3 id="installed-plugins-json-holds-a-record-this-version-cannot-read">
638 `installed_plugins.json holds a record under "<id>" that this version of Claude Code cannot read`
639</h3>
640
641The message surfaces in these forms:
642
643* **`claude plugin list`**: prints it as a `Note:`
644* **`claude plugin install`, `uninstall`, and `update`**: refuse with `Plugin "<name>" was not installed:`, `Plugin "<name>" was not uninstalled:`, or `Plugin "<name>" was not updated:`, followed by the same text
645* **`--json` on any of those three commands**: the result line carries the same `message` and `failureCode: "install_records_unreadable"`
646* **Several such records**: the message reads `holds records under`
647* **The whole file declares a format this version doesn't know**: the message reads `installed_plugins.json is in a format (version <N>) that this version of Claude Code does not know` instead
648
649The named record in `installed_plugins.json` is valid JSON under a valid plugin id, but its fields don't parse for this version. Most likely another version of Claude Code wrote it, perhaps a newer one.
650
651While the record is there, this version doesn't rewrite the file, so the record isn't lost.
652
653Take the message's options in order:
654
6551. Update Claude Code with `claude update`.
6562. If you can't update, uninstall the named plugin with the version of Claude Code that wrote the record.
6573. If neither helps, delete the record from `installed_plugins.json` by hand, then restart Claude Code or run `/reload-plugins`.
658
659<h3 id="installed-plugins-json-could-not-be-read-and-was-rebuilt">
660 `installed_plugins.json could not be read and was rebuilt`
661</h3>
662
663`claude plugin list` prints this note, with the path of a kept file named `installed_plugins.unreadable.<date>.<hash>.kept`, for as long as that file sits beside `installed_plugins.json`.
664
665An `installed_plugins.json` that isn't valid JSON, or isn't a list of plugins, can't say what you installed.
666
667Open the `.kept` file to see what the old file recorded, and reinstall the plugins you're missing. Claude Code never reads the file back, and the file ages out on the [`cleanupPeriodDays`](/docs/en/settings-reference#cleanupperioddays) schedule.
668
669<h3 id="install-records-under-names-that-no-version-can-use">
670 `install records under names that no version of Claude Code can use were removed from installed_plugins.json`
671</h3>
672
673`claude plugin list` prints this note, with the path of a copy named `installed_plugins.set-aside.<date>.<hash>.json`, for as long as that copy sits beside `installed_plugins.json`. The note ends `Nothing needs doing about these copies.`
674
675A record in `installed_plugins.json` sat under a key that isn't a valid plugin id, so no version of Claude Code can use it. The rest of the file loads normally.
676
677Claude 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.
678
637679<h3 id="a-plugin-you-disabled-still-loads">
638680 `Disabled in ~/.claude/settings.json but still loads`
639681</h3>
from line 987
945987| `Path contains "..": <path>` under `plugins[N].source` | Error | Use paths relative to the marketplace root without `..` segments. |
946988| `Marketplace name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the name, such as an escape or a newline. |
947989| `Plugin name cannot contain control or bidirectional-formatting characters` | Error | Remove the character from the plugin `name`. |
990| `Claude Code cannot install plugins from marketplace "<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. Change the marketplace's "name".` | Error | Rename the marketplace to fit the rule the message states. |
991| `Claude Code cannot install plugin "<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. Change this entry's "name".` | Error | Rename the entry to fit the rule the message states. |
948992| `Marketplace has no plugins defined` | Warning | Add at least one entry to `plugins`. |
949993| `No marketplace description provided` | Warning | Add a top-level `description`. |
950| `Plugin name "<name>" is not kebab-case` under `plugins[N] plugin.json → name` | Warning | Rename to lowercase letters, digits, and hyphens. Claude Code accepts other forms, but the claude.ai marketplace sync rejects them. |
994| `Plugin name "<name>" is not kebab-case` under `plugins[N] plugin.json → name` | Warning | Rename to lowercase letters, digits, and hyphens; the claude.ai marketplace sync requires that form. |
951995| `Entry declares version "<a>" but <path>/plugin.json says "<b>"` | Warning | Update the entry to match `plugin.json`, which is authoritative at install time. |
952996| `Marketplace name "<name>" is reserved in Claude Desktop` | Warning | Rename the marketplace. Claude Desktop's managed marketplace sync rejects `org`, `org-provisioned`, and `unknown` in any casing. |
953997| `Marketplace name "<name>" is not accepted by Claude Desktop` or `Plugin name "<name>" is not accepted by Claude Desktop` | Warning | Rename to at most 128 characters of letters, digits, `.`, `_`, and `-`, starting with a letter or digit. |
No line in this hunk matches that.