{"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":809,"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":791,"sourceCodeEnd":827,"githubUrl":"https://github.com/ruvnet/ruflo/blob/2602b642d92234c710ffbe96bfb33007d481ceab/v3/@claude-flow/cli/src/mcp-server.ts#L791-L827","documentation":"waitForReady() polls checkHealth() every 100 ms until the timeout (default 10 s) elapses; if the server never reports healthy it throws 'Server failed to start within timeout'. For stdio transport the method returns immediately, so this error is specific to network transports (http) where readiness depends on the spawned process actually binding and answering health checks.","triggerScenarios":"HTTP transport on a busy or already-bound port so the child crashes and health never passes; cold start with heavy initialization (memory/ONNX model loading) exceeding the 10 s default; host/port misconfiguration (binding 0.0.0.0 vs configured host, firewall dropping health probes); an underpowered CI runner where startup is systematically slow.","commonSituations":"CI pipelines on shared runners with slow disk; first run downloading models; port conflicts with a previous server (see 226) causing crash-restart loops; container CPU limits throttling startup past the timeout.","solutions":["Check server logs and confirm the port is free and the configured host is bindable (lsof -i :PORT) — a crashed child never becomes healthy","Raise the readiness timeout passed to waitForReady()/start options on slow machines, or retry start with backoff","Reduce startup work (defer model/memory initialization) or pre-warm caches so health passes sooner","If it never turns healthy even with generous timeouts, run `npx @claude-flow/cli@latest doctor` to check Node version and environment"],"exampleFix":"// before — default 10s readiness window on a cold CI runner\nawait server.start(); // throws 'Server failed to start within timeout'\n\n// after — explicit longer timeout + one retry\nawait server.start({ readyTimeout: 60_000 });\n// or: await retry(() => server.start(), { retries: 2, backoffMs: 5000 });","handlingStrategy":"retry","validationCode":"// Pre-flight for http transport: ensure the port is free before start\nimport { createServer } from 'node:net';\n\nawait new Promise<void>((res, rej) => {\n  const probe = createServer();\n  probe.once('error', rej).once('listening', () => probe.close(() => res()));\n  probe.listen({ port: options.port, host: options.host });\n});","typeGuard":null,"tryCatchPattern":"async function startWithRetry(server, { retries = 2, timeoutMs = 30_000 } = {}) {\n  for (let attempt = 0; ; attempt++) {\n    try { return await server.start(); }\n    catch (e) {\n      if ((e as Error).message !== 'Server failed to start within timeout' || attempt >= retries) throw e;\n      await server.stop().catch(() => {});\n      await new Promise(r => setTimeout(r, 2 ** attempt * 1000)); // backoff\n    }\n  }\n}","preventionTips":["Raise the readiness timeout on slow CI/cold-start environments","Free the port and check logs before retrying — a crashed child never becomes healthy","Pre-warm model/memory caches so health checks pass inside the window"],"tags":["mcp","startup","timeout","health-check","http-transport"],"backgroundTag":"service-startup-timeout","analyzedSha":"2602b642d92234c710ffbe96bfb33007d481ceab","analyzedAt":"2026-08-18T21:34:22.708Z","contentChangedAt":"2026-08-18T21:34:22.708Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}