{"record":{"id":"1ea0e659dffc83f5","repo":"mastra-ai/mastra","slug":"failed-to-spawn-lsp-server","errorCode":null,"errorMessage":"Failed to spawn LSP server","messagePattern":"Failed to spawn LSP server","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"mastracode/sdk/src/lsp/client.ts","lineNumber":31,"sourceCode":"  private process: ChildProcess | null = null;\n  private serverInfo: LSPServerInfo;\n  private workspaceRoot: string;\n  private diagnostics: Map<string, Diagnostic[]> = new Map();\n  private initializationOptions: any = null;\n\n  constructor(serverInfo: LSPServerInfo, workspaceRoot: string) {\n    this.serverInfo = serverInfo;\n    this.workspaceRoot = workspaceRoot;\n  }\n\n  /**\n   * Initialize the LSP connection\n   */\n  async initialize(): Promise<void> {\n    const spawnResult = await this.serverInfo.spawn(this.workspaceRoot);\n\n    if (!spawnResult) {\n      throw new Error('Failed to spawn LSP server');\n    }\n\n    // Handle both ChildProcess and { process: ChildProcess, initialization? } formats\n    let initializationOptions: any = undefined;\n    if ('process' in spawnResult) {\n      this.process = spawnResult.process;\n      initializationOptions = spawnResult.initialization;\n    } else {\n      this.process = spawnResult;\n    }\n\n    if (!this.process.stdin || !this.process.stdout) {\n      throw new Error('Failed to create LSP process with proper stdio');\n    }\n\n    const reader = new StreamMessageReader(this.process.stdout);\n    const writer = new StreamMessageWriter(this.process.stdin);\n    this.connection = createMessageConnection(reader, writer);","sourceCodeStart":13,"sourceCodeEnd":49,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/sdk/src/lsp/client.ts#L13-L49","documentation":"LSPClient.initialize() starts the language server by calling serverInfo.spawn(workspaceRoot). If spawn returns null/false (the server binary could not be launched), the client throws Error('Failed to spawn LSP server'). This is the wrapper thrown when the underlying spawn callback yields no ChildProcess at all.","triggerScenarios":"initialize() (called via restart or the cached initPromise) when the configured LSP server's spawn callback fails — server command not found on PATH, wrong executablePath, spawn error swallowed by the serverInfo implementation returning null.","commonSituations":"Language server binary not installed (e.g. typescript-language-server, gopls missing); server installed via a version manager not active in the CLI's environment; typo in server command config; Windows shell quirks where the command isn't resolvable.","solutions":["Verify the LSP server binary is installed and resolvable: run its command manually (e.g. `typescript-language-server --version`).","Check the LSPServerInfo spawn configuration — correct command, args, and optional executablePath override.","Ensure PATH in the environment running the SDK includes the server's install location (nvm/asdf/volta shims, global npm bin).","Wrap initialize() in try/catch and implement a fallback (degrade without LSP features) or surface install instructions."],"exampleFix":"// before\nawait client.initialize(); // throws: gopls not on PATH\n// after\nif (!commandExists(serverInfo.command)) {\n  throw new Error(`LSP server '${serverInfo.command}' not installed; install it first`);\n}\nawait client.initialize();","handlingStrategy":"try-catch","validationCode":"import { spawnSync } from 'node:child_process';\nfunction commandExists(cmd: string): boolean {\n  const r = spawnSync(cmd, ['--version'], { stdio: 'ignore' });\n  return !r.error;\n}\n// call before initialize(): if (!commandExists(serverInfo.command)) promptInstall(serverInfo.command);","typeGuard":null,"tryCatchPattern":"try {\n  await client.initialize();\n} catch (e) {\n  if (e.message === 'Failed to spawn LSP server') {\n    logger.warn(`LSP server '${serverInfo.command}' unavailable; continuing without language features`);\n    return; // degrade gracefully\n  }\n  throw e;\n}","preventionTips":["Document and verify required LSP binaries in project setup (install scripts, doctor command).","Check PATH availability of the server command at startup and warn early.","Pin the server command with an absolute path or executablePath setting in managed environments."],"tags":["lsp","spawn-failure","process"],"backgroundTag":"lsp-server-spawn-failure","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}