{"record":{"id":"cf441ad7ecf382ca","repo":"ruvnet/ruflo","slug":"server-failed-to-start-within-timeout","errorCode":null,"errorMessage":"Server failed to start within timeout","messagePattern":"Server failed to start within timeout","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/@claude-flow/cli/src/mcp-server.ts","lineNumber":751,"sourceCode":"   * Wait for server to be ready\n   */\n  private async waitForReady(timeout = 10000): Promise<void> {\n    // For stdio transport, we're ready immediately (in-process)\n    if (this.options.transport === 'stdio') {\n      return;\n    }\n\n    const startTime = Date.now();\n\n    while (Date.now() - startTime < timeout) {\n      const health = await this.checkHealth();\n      if (health.healthy) {\n        return;\n      }\n      await this.sleep(100);\n    }\n\n    throw new Error('Server failed to start within timeout');\n  }\n\n  /**\n   * Wait for process to exit\n   */\n  private async waitForExit(timeout: number): Promise<void> {\n    if (!this.process) return;\n\n    return new Promise((resolve) => {\n      const timer = setTimeout(() => {\n        resolve();\n      }, timeout);\n\n      this.process!.once('exit', () => {\n        clearTimeout(timer);\n        resolve();\n      });\n    });","sourceCodeStart":733,"sourceCodeEnd":769,"githubUrl":"https://github.com/ruvnet/ruflo/blob/6b01dc5a687b26b3e218f796de45ec51f8fa9e8c/v3/@claude-flow/cli/src/mcp-server.ts#L733-L769","documentation":"Thrown by MCPServerManager.waitForReady() after polling checkHealth() every 100ms for the configured timeout (default 10000ms) without ever seeing healthy=true. This is the HTTP/WebSocket path only — stdio returns immediately. It means the in-process HTTP server started but never answered the health endpoint (or checkHealth() keeps failing its TCP/HTTP probe).","triggerScenarios":"The HTTP server bind() is blocked by a firewall or the port is in TIME_WAIT; the underlying createMCPServer threw asynchronously after start() returned; the health endpoint route is misconfigured; the timeout is too short for a slow-booting dependency (sql.js WASM load, embeddings model init).","commonSituations":"CI environment with slow disk or network causing cold-start > 10s; port conflict where the OS hands out the port slowly; a regression in the health route; the host is resource-starved (CPU throttled container).","solutions":["Raise the timeout: pass a larger `timeout` to waitForReady, or set the relevant startup-timeout option in MCPServerOptions.","Manually probe the health endpoint (`curl http://localhost:<port>/health`) to see if the server is up but the route differs from what checkHealth expects.","Check that the port is actually free and bindable: `lsof -i:<port>` / `ss -ltn`.","Profile cold-start — if sql.js/embeddings init dominates, warm those before start() or move to a persisted cache."],"exampleFix":"// before — default 10s timeout too short in slow CI\nawait manager.start();\n// after\nawait manager.start({ startupTimeoutMs: 30000 });","handlingStrategy":"retry","validationCode":"null","typeGuard":"null","tryCatchPattern":"const tryStart = async (timeoutMs: number) => {\n  try { return await manager.start({ startupTimeoutMs: timeoutMs }); }\n  catch (e) {\n    if (/Server failed to start within timeout/.test(String(e?.message ?? ''))) {\n      // backoff and retry once with a longer timeout\n      await new Promise(r => setTimeout(r, 2000));\n      return manager.start({ startupTimeoutMs: timeoutMs * 2 });\n    }\n    throw e;\n  }\n};","preventionTips":["Size startupTimeoutMs to your slowest cold-start (sql.js WASM, embeddings model load).","Probe the port independently (`ss -ltn`) before calling start to rule out conflicts.","Warm expensive deps (memory init, model load) before start() in latency-sensitive hosts."],"tags":["mcp","server","health","timeout","startup"],"backgroundTag":null,"analyzedSha":"6b01dc5a687b26b3e218f796de45ec51f8fa9e8c","analyzedAt":"2026-08-12T13:20:50.148Z","schemaVersion":2},"datasetVersion":"2026-08-12T23:17:12.415Z"}