Error Handling & Logging
Relevant source files
The following files were used as context for generating this wiki page:
Error Handling & Logging in the lsp-mcp-server project provides a structured mechanism for capturing, reporting, and recording system behaviors and failures. The system is designed to bridge Language Server Protocol (LSP) diagnostics and errors into the Model Context Protocol (MCP) framework, ensuring that clients like Claude Code receive actionable feedback when operations fail.
The architecture separates internal system logging—directed to stderr to avoid corrupting stdio communication—from structured errors returned to the user via the LSPError class. This ensures that technical failures (e.g., server crashes) and protocol-level errors (e.g., invalid positions) are handled consistently across the 24+ MCP tools provided by the server.
Sources: CLAUDE.md:120-125, src/utils/logger.ts:40-66
Structured Error Handling
The project uses a custom LSPError class to provide consistent error responses across all tool handlers. This class includes an error code, a human-readable message, an actionable suggestion for the user, and optional technical details such as the relevant server_id or file_path.
Sources: src/types.ts:257-279, CLAUDE.md:120-125
Error Codes
The system categorizes failures into three primary groups: Server Lifecycle, Request, and Protocol errors, managed via the LSPErrorCode enum.
| Category | Error Codes | Description |
|---|---|---|
| Server Lifecycle | SERVER_NOT_FOUND, SERVER_START_FAILED, SERVER_CRASHED, SERVER_TIMEOUT, SERVER_NOT_READY | Issues related to spawning, connecting to, or maintaining language server processes. |
| Request | FILE_NOT_FOUND, FILE_NOT_READABLE, INVALID_POSITION, UNSUPPORTED_LANGUAGE, CAPABILITY_NOT_SUPPORTED, RENAME_NOT_ALLOWED | Validation failures or requests for features not supported by the specific LSP or file. |
| Protocol | INVALID_RESPONSE, REQUEST_CANCELLED | Failures in the communication between the MCP server and the underlying LSP server. |
| Sources: src/types.ts:238-255 |
Error Propagation Flow
When an error occurs during a tool execution (e.g., in src/tools/code-actions.ts), the handler throws an LSPError. The main request handler in src/index.ts catches this, converts it to JSON using the toJSON() method, and returns it to the MCP client with the isError flag set.
Logging System
The logging system is implemented in src/utils/logger.ts and is designed to provide visibility into server operations without interfering with the stdio transport used for MCP/LSP communication.
Logger Architecture
The Logger class writes exclusively to process.stderr. This is a critical design decision to ensure that log messages do not get mixed with the JSON-RPC messages sent over process.stdout.
Sources: src/utils/logger.ts:40-66
Log Levels
The server supports four standard log levels, which can be configured via the logLevel field in the global configuration or the LOG_LEVEL environment variable.
| Level | Priority | Purpose |
|---|---|---|
debug | 0 | Verbose output for development and troubleshooting. |
info | 1 | General operational messages (e.g., server startup/shutdown). |
warn | 2 | Non-fatal issues that may require attention. |
error | 3 | Critical failures and exceptions. |
| Sources: src/utils/logger.ts:32-38, src/types.ts:104 |
Exception Handling
The logger includes a specific exception method that extracts the name, message, and stack trace from standard JavaScript Error objects, ensuring that stack information is preserved in the logs for debugging.
Sources: src/utils/logger.ts:88-98
// Example of logging an internal tool failure in src/index.ts
const message = error instanceof Error ? error.message : String(error);
log('error', `Tool ${name} failed: ${message}`);
Sources: src/index.ts:756-757
Diagnostics and Validation
Beyond system errors, the server handles "code errors" (diagnostics) pushed by language servers.
Diagnostics Logic
Diagnostics are push-based. The LSPClient receives publishDiagnostics notifications and caches them in a DiagnosticsCache. Users retrieve these via lsp_diagnostics or lsp_workspace_diagnostics.
Sources: CLAUDE.md:43-45, src/tools/diagnostics.ts:40-90
Validation Errors
Input validation is performed using Zod schemas defined in src/schemas/tool-schemas.ts. If an MCP request contains invalid parameters, the src/index.ts handler catches the Zod error and returns a structured INVALID_INPUT response containing the specific validation issues.
Sources: src/index.ts:738-753, src/schemas/tool-schemas.ts:44-55
File and Path Security
The system implements security-focused error handling for file operations. For example, validatePathWithinWorkspace is used in file-modifying tools like lsp_code_actions.ts to throw errors if an operation attempts to write outside the detected workspace boundary.
Sources: src/tools/code-actions.ts:117-120, CLAUDE.md:104-106
Summary
Error handling in lsp-mcp-server is a multi-layered system that distinguishes between input validation (Zod), protocol-level errors (LSPError), and internal system logging (Logger). By funneling all technical logs to stderr and all user-facing errors into a structured JSON format, the server maintains high reliability and provides clear debugging information for both developers and end-users.
Sources: src/utils/logger.ts:63-66, src/types.ts:257-279, src/index.ts:717-765