[DOCS] Plugin LSP server init failure no longer blocks another plugin's valid LSP server for the same file extension
Open 💬 0 comments Opened Jul 8, 2026 by coygeek
Documentation Type
Incorrect/outdated documentation
Documentation Location
https://code.claude.com/docs/en/plugins-reference
Section/Topic
The "LSP servers" subsection under "Plugin components" (around the extensionToLanguage field, the .lsp.json format, and the merge rules for component types). The matching "Code intelligence issues" troubleshooting list at https://code.claude.com/docs/en/discover-plugins also needs a parallel update.
Current Documentation
https://code.claude.com/docs/en/plugins-reference describes the LSP server block in a plugin's .lsp.json (or inline lspServers in plugin.json) and the optional fields, but it never says what happens when two plugins both register an LSP server for the same file extension, nor what happens when one of those servers fails to initialize:
```json theme={null}
{
"go": {
"command": "gopls",
"args": ["serve"],
"extensionToLanguage": {
".go": "go"
}
}
}
| Field | Description |
| :-------------------- | :------------------------------------------- |
| `command` | The LSP binary to execute (must be in PATH) |
| `extensionToLanguage` | Maps file extensions to language identifiers |
The same page's "Path behavior rules" section (around line 605) says only:
> **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine
The "Code intelligence issues" troubleshooting list at `https://code.claude.com/docs/en/discover-plugins` (around line 483) names three failure cases and never mentions the multi-plugin-same-extension or initialization-failure case:
> * **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details.
> * **High memory usage**: language servers like `rust-analyzer` and `pyright` can consume significant memory on large projects. If you experience memory issues, disable the plugin with `/plugin disable <plugin-name>` and rely on Claude's built-in search tools instead.
> * **False positive diagnostics in monorepos**: language servers may report unresolved import errors for internal packages if the workspace isn't configured correctly. These don't affect Claude's ability to edit code.
Neither page mentions what happens when one plugin's LSP server fails to initialize, even though `extensionToLanguage` is the field that lets two plugins both claim the same extension.
### What's Wrong or Missing?
### A. The v2.1.205 plugin-LSP resilience fix is not reflected anywhere
The v2.1.205 changelog records:
> Fixed a plugin LSP server that fails to initialize preventing a valid LSP server from another plugin handling the same file extension
Before v2.1.205, a plugin that declared an LSP server for a file extension (for example, a custom TypeScript plugin that mapped `.ts` to `typescript` in its `extensionToLanguage`) could not coexist with another plugin that also mapped `.ts`. If the first plugin's `command` was missing from `PATH`, the binary failed its `initialize` handshake, or the server crashed before sending `initialized`, the second plugin's server was blocked from handling `.ts` files. The user saw "no server available" errors or silent loss of diagnostics/navigation, even though a working plugin was installed.
After v2.1.205, an LSP server that fails to initialize from one plugin no longer prevents a valid LSP server from a different plugin from handling the same file extension. The two plugins' servers are evaluated independently, so the working plugin can serve the extension regardless of what the broken one does at startup.
`plugins-reference.md` and `discover-plugins.md` describe the `extensionToLanguage` field, the troubleshooting list, and the merge rules for component types, but neither page says anything about the per-plugin initialization isolation. A user on v2.1.205 who reads the docs has no way to learn that:
1. Multiple plugins can each map the same file extension to their own language server.
2. A failure to initialize in one plugin's server is contained to that plugin.
3. The "Language server not starting" troubleshooting item is now scoped to the failing plugin, not the language as a whole.
### B. The `extensionToLanguage` field description leaves the multi-plugin case undocumented
The `extensionToLanguage` field description is "Maps file extensions to language identifiers." That sentence is consistent with a single source of truth, but the v2.1.205 fix is what makes a per-plugin `extensionToLanguage` map composable with another plugin's map. Without a note, a user who reads the field and imagines installing two LSP plugins that both handle `.py` has no way to tell from the docs that v2.1.205 is the version where that composition became reliable, or that a broken `command` on one plugin used to break both.
### C. The Code intelligence issues list has no entry for this case
When a user follows the "Language server not starting" troubleshooting item and confirms the binary is installed for the working plugin, the docs offer no next step for the case where a different plugin's broken LSP server is the actual cause. The `Errors` tab in `/plugin` surfaces the broken plugin's failure, but neither the troubleshooting list nor the LSP field description tells the user that the two plugins are evaluated independently in v2.1.205.
### Suggested Improvement
**Before** (`plugins-reference.md` "LSP servers" field table):
> | `extensionToLanguage` | Maps file extensions to language identifiers |
**After** (add the v2.1.205 note under the table):
> | `extensionToLanguage` | Maps file extensions to language identifiers |
>
> {/* min-version: 2.1.205 */}Multiple plugins can each declare an `extensionToLanguage` map for the same file extension. When two plugins both map `.ts` (or any other extension), Claude Code evaluates each plugin's LSP server independently: a failure to initialize in one plugin's server does not block the other plugin's server from handling the same files. Before v2.1.205, a failing `initialize` handshake in one plugin's server could prevent the other plugin's server from serving the same extension, even when that other server was healthy.
**Before** (`plugins-reference.md` "Path behavior rules" merge-rules bullet):
> * **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). See each section for how multiple sources combine
**After** (extend the LSP sentence in that section):
> * **Own merge rules**: [hooks](#hooks), [MCP servers](#mcp-servers), and [LSP servers](#lsp-servers). LSP servers merge by file extension: each plugin's `extensionToLanguage` map is independent, and a server that fails to initialize in one plugin does not block a valid server in another plugin from handling the same extension (v2.1.205 and later). See each section for how multiple sources combine.
**Before** (`discover-plugins.md` "Code intelligence issues" troubleshooting list):
> * **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details.
**After** (split the entry to cover the new case):
> * **Language server not starting**: verify the binary is installed and available in your `$PATH`. Check the `/plugin` Errors tab for details. {/* min-version: 2.1.205 */}If the binary is installed and the Errors tab names a specific plugin, a different plugin's LSP server for the same file extension is unaffected. A failure to initialize in one plugin's server no longer prevents a valid server in another plugin from handling the same files (v2.1.205 and later).
> * **Two plugins both map the same file extension**: each plugin's `extensionToLanguage` is independent. As of v2.1.205, a server that fails to initialize in one plugin does not block the other plugin's server from serving the same extension. Check `/plugin` Errors if a working plugin appears to have stopped responding, since a different plugin's failed initialize is the more likely cause.
### Impact
Medium - Makes feature difficult to understand
### Additional Context
The "Manage installed plugins" / "Not used recently" section in `discover-plugins.md` (around line 314) already documents the v2.1.203 change that started counting LSP activity as plugin use. The companion v2.1.205 change about plugin-LSP initialization isolation belongs in the same area, because both fixes describe what happens when multiple LSP plugins are present. The "Code intelligence issues" list is the right place because the failure is observed as "language server not starting" in the user's session, even though the proximate cause is another plugin's broken server.
**Affected Pages:**
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/plugins-reference | 192-274, 605 | "LSP servers" component section and merge-rules bullet for component types |
| https://code.claude.com/docs/en/discover-plugins | 483-487 | "Code intelligence issues" troubleshooting list |
**Total scope:** 2 pages affected