{"record":{"id":"0d492f4ff9f15599","repo":"BabylonJS/Babylon.js","slug":"unable-to-connect-to-the-inspector-bridge-on-port","errorCode":null,"errorMessage":"Unable to connect to the Inspector bridge on port ${port} after spawning it.","messagePattern":"Unable to connect to the Inspector bridge on port (.+?) after spawning it\\.","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/dev/inspector-v2/src/cli/cli.ts","lineNumber":216,"sourceCode":"    try {\r\n        return await ConnectToBridge(port);\r\n    } catch {\r\n        // Bridge not running — spawn it.\r\n        SpawnBridge(bridgeScript);\r\n    }\r\n\r\n    for (let i = 0; i < maxRetries; i++) {\r\n        // eslint-disable-next-line no-await-in-loop\r\n        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));\r\n        try {\r\n            // eslint-disable-next-line no-await-in-loop\r\n            return await ConnectToBridge(port);\r\n        } catch {\r\n            // Keep retrying.\r\n        }\r\n    }\r\n\r\n    throw new Error(`Unable to connect to the Inspector bridge on port ${port} after spawning it.`);\r\n}\r\n\r\n/**\r\n * Connects to the bridge, runs the provided callback, and closes the socket.\r\n * @param bridgeScript Optional path to the bridge script.\r\n * @param fn The callback to run with the connected socket.\r\n */\r\nasync function WithBridge(bridgeScript: string | undefined, fn: (socket: WebSocket) => Promise<void>): Promise<void> {\r\n    const socket = await EnsureBridge(Config.cliPort, bridgeScript);\r\n    try {\r\n        await fn(socket);\r\n    } finally {\r\n        socket.close();\r\n    }\r\n}\r\n\r\n/**\r\n * Parses and validates an explicit session id string against the list of active sessions.\r","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/BabylonJS/Babylon.js/blob/0592b347b8a4ee0236089ea86a749cacfdb266d8/packages/dev/inspector-v2/src/cli/cli.ts#L198-L234","documentation":"The inspector-v2 CLI spawns a bridge process and then repeatedly attempts a WebSocket connection to it on the given port. If every retry fails after the spawn, it throws this error indicating the bridge never became reachable.","triggerScenarios":"Running a CLI command whose spawned bridge process crashed on startup, listens on a different port, is blocked by a firewall, or takes longer than the retry window to open its WebSocket server.","commonSituations":"Port already in use by another process or blocked by corporate firewall/VPN; stale bridge from a previous run holding the port; Node version mismatch causing the bridge script to crash; running inside a container where the port isn't exposed.","solutions":["Check the spawned bridge's stdout/stderr logs for a startup crash and fix that root cause first.","Verify the port is free and not blocked: lsof -i :<port> / firewall rules; pick a different port if occupied.","Increase the retry count/timeout in EnsureBridge if the bridge is slow to start (cold machine, slow startup).","Kill stale bridge processes from earlier runs that may be holding the port.","Confirm host/port configuration matches between the CLI and the bridge script being spawned."],"exampleFix":"// before\nawait EnsureBridge(48620); // bridge never starts, port blocked\n// after\nconst port = await findFreePort(48620);\nawait EnsureBridge(port, { retries: 20, retryDelayMs: 500 }); // more patience + known-free port","handlingStrategy":"retry","validationCode":"async function bridgeReachable(port: number): Promise<boolean> {\n  try {\n    const res = await fetch(`http://127.0.0.1:${port}/health`);\n    return res.ok;\n  } catch { return false; }\n}","typeGuard":null,"tryCatchPattern":"try {\n  await EnsureBridge(port);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith(\"Unable to connect to the Inspector bridge\")) {\n    console.error(`Bridge on port ${port} unreachable. Check bridge logs / port availability.`);\n    process.exitCode = 2;\n  } else throw e;\n}","preventionTips":["Verify the port is free (lsof/netstat) and not blocked by firewall or VPN before spawning","Capture and inspect spawned bridge stdout/stderr for startup crashes","Add generous retries with backoff for slow-start environments (CI, containers)","Clean up stale bridge processes between runs"],"tags":["network","websocket","cli","connection"],"backgroundTag":"connection-refused","analyzedSha":"0592b347b8a4ee0236089ea86a749cacfdb266d8","analyzedAt":"2026-08-30T15:11:20.442Z","schemaVersion":2},"datasetVersion":"2026-08-30T18:17:15.746Z"}