claude-code - 💡(How to fix) Fix [BUG] lspServers restartOnCrash (documented field) fails LSP init: "not yet implemented"

Summary

A documented lspServers field — restartOnCrash — causes the entire LSP server to fail initialization when present in a plugin's plugin.json. The runtime rejects it with "not yet implemented. Remove this field from the configuration", yet the docs list it as a standard optional field with no such annotation. The result is silent loss of language-server diagnostics: affected servers never start, and the only signal is an [ERROR] line in the debug log.

maxRestarts is documented the same way and is likely affected identically (not separately verified).

Docs say it's supported

The LSP servers reference (https://code.claude.com/docs/en/plugins-reference.md) lists both fields in the optional-fields table with no implementation-status note:

restartOnCrash   | Whether to automatically restart the server if it crashes
maxRestarts      | Maximum number of restart attempts before giving up

Runtime rejects it — and drops the whole server

With restartOnCrash: true set on several plugins, startup produced (debug log, v2.1.157):

[ERROR] Failed to initialize LSP server plugin:py-dev:ruff: LSP server 'plugin:py-dev:ruff': restartOnCrash is not yet implemented. Remove this field from the configuration.
[ERROR] Failed to initialize LSP server plugin:py-dev:ty: ... restartOnCrash is not yet implemented. ...
[ERROR] Failed to initialize LSP server plugin:zig-dev:zls: ... restartOnCrash is not yet implemented. ...
[DEBUG] LSP manager initialized with 2 servers

Multiple servers were dropped; only those whose configs lacked the field survived. No publishDiagnostics ever flowed for the dropped servers, with no user-facing indication — diagnostics simply never appeared.

Repro

1. In a plugin's .claude-plugin/plugin.json, add "restartOnCrash": true to an lspServers entry:

   {
     "lspServers": {
       "ruff": {
         "command": "ruff",
         "args": ["server"],
         "extensionToLanguage": { ".py": "python" },
         "restartOnCrash": true
       }
     }
   }

2. Start Claude Code with --debug in a project where that plugin is enabled.
3. Edit a matching file (e.g. a .py) and observe: no diagnostics.
4. Debug log shows Failed to initialize LSP server ... restartOnCrash is not yet implemented, and the server is absent from the initialized count.

Removing the field restores the server and diagnostics flow correctly.

Expected

One of:

• Implement the field, or
• Mark it (not yet implemented) in the docs and ignore it with a warning rather than failing server init.

An unimplemented-but-documented field should not silently disable a language server. A field-level warning that leaves the server running would match the principle of least surprise.

Environment

• Claude Code 2.1.157 (native install, macOS / Darwin 25.5.0)