{"record":{"id":"2eefa87dc93d9646","repo":"ruvnet/ruflo","slug":"internal-error","errorCode":"INTERNAL_ERROR","errorMessage":"Failed to start server","messagePattern":"Failed to start server","errorType":"exception","errorClass":"MCPServerError","httpStatus":null,"severity":"critical","filePath":"v3/@claude-flow/shared/src/mcp/server.ts","lineNumber":212,"sourceCode":"      // Register built-in tools\n      await this.registerBuiltInTools();\n\n      this.running = true;\n      this.startupDuration = performance.now() - startTime;\n\n      this.logger.info('MCP server started', {\n        startupTime: `${this.startupDuration.toFixed(2)}ms`,\n        tools: this.toolRegistry.getToolCount(),\n      });\n\n      this.emit('server:started', {\n        startupTime: this.startupDuration,\n        tools: this.toolRegistry.getToolCount(),\n      });\n\n    } catch (error) {\n      this.logger.error('Failed to start MCP server', { error });\n      throw new MCPServerError('Failed to start server', ErrorCodes.INTERNAL_ERROR, { error });\n    }\n  }\n\n  /**\n   * Stop the MCP server\n   */\n  async stop(): Promise<void> {\n    if (!this.running) {\n      return;\n    }\n\n    this.logger.info('Stopping MCP server');\n\n    try {\n      // Stop transport\n      if (this.transport) {\n        await this.transport.stop();\n        this.transport = undefined;","sourceCodeStart":194,"sourceCodeEnd":230,"githubUrl":"https://github.com/ruvnet/ruflo/blob/fa13ee4ad60ac2090b1480656eb233521790d640/v3/@claude-flow/shared/src/mcp/server.ts#L194-L230","documentation":"This is the catch-all at the end of MCPServer.start(): any failure raised while bringing up the transport or server internals is re-thrown as MCPServerError('Failed to start server') with code ErrorCodes.INTERNAL_ERROR (-32603), and the original error is attached in the error data (third constructor argument { error }). The wrapper message is generic on purpose - the actionable cause is the attached original error and the preceding 'Failed to start MCP server' log line.","triggerScenarios":"HTTP/WebSocket transport binding an already-used port (EADDRINUSE); stdio transport with closed or unavailable stdin/stdout (containers, daemons); transport config malformed so createTransport throws inside start(); tool registry or event-handler setup throwing during startup.","commonSituations":"Two processes configured on the same port because an old dev-server instance still holds it; running stdio transport where stdin is not available; a version upgrade adding required config fields; insufficient permissions to bind a privileged port.","solutions":["Read the attached cause first: catch the error and inspect (err as MCPServerError).data.error, or the 'Failed to start MCP server' log entry - fix the underlying error, not this wrapper","Port conflict: find and stop the holder (lsof -i :PORT) or change the configured port","Validate transport config before start(): host/port present for http/ws, usable streams for stdio","In non-TTY environments, switch away from stdio transport or provide explicit inputStream/outputStream in config"],"exampleFix":"// before\nawait server.start(); // opaque 'Failed to start server' INTERNAL_ERROR\n\n// after\nimport { MCPServerError } from './mcp/types';\ntry {\n  await server.start();\n} catch (e) {\n  const cause = (e instanceof MCPServerError ? (e.data as any)?.error : undefined) ?? e;\n  if ((cause as NodeJS.ErrnoException)?.code === 'EADDRINUSE') {\n    console.error('Port already in use - stop the old process or change the port');\n  }\n  throw e;\n}","handlingStrategy":"try-catch","validationCode":"// pre-flight common causes before start()\nimport { checkPortInUse } from './net';\nif (config.transport === 'http' || config.transport === 'websocket') {\n  if (await checkPortInUse(config.port)) {\n    throw new Error(`Port ${config.port} already in use - choose another or stop the holder`);\n  }\n}\nawait server.start();","typeGuard":null,"tryCatchPattern":"try {\n  await server.start();\n} catch (e) {\n  const mcpErr = e as MCPServerError;\n  const cause = (mcpErr?.data as { error?: unknown } | undefined)?.error ?? e;\n  logger.error('MCP server failed to start', { cause }); // surface the REAL cause\n  process.exitCode = 1; // fail fast: do not run half-started\n}","preventionTips":["Always log the attached cause (e.data.error), never only the wrapper message","Pre-flight port availability for network transports before start","Run one server per port per host; containerize to avoid collisions","Exit on startup failure rather than continuing with a broken server"],"tags":["mcp","server","startup","internal-error","error-wrapping"],"backgroundTag":"server-startup-failed","analyzedSha":"fa13ee4ad60ac2090b1480656eb233521790d640","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}