Unable to connect to the Inspector bridge on port ${port} af

Error message

Unable to connect to the Inspector bridge on port ${port} after spawning it.

What it means

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.

Source

Thrown at packages/dev/inspector-v2/src/cli/cli.ts:216

    try {
        return await ConnectToBridge(port);
    } catch {
        // Bridge not running — spawn it.
        SpawnBridge(bridgeScript);
    }

    for (let i = 0; i < maxRetries; i++) {
        // eslint-disable-next-line no-await-in-loop
        await new Promise((resolve) => setTimeout(resolve, retryDelayMs));
        try {
            // eslint-disable-next-line no-await-in-loop
            return await ConnectToBridge(port);
        } catch {
            // Keep retrying.
        }
    }

    throw new Error(`Unable to connect to the Inspector bridge on port ${port} after spawning it.`);
}

/**
 * Connects to the bridge, runs the provided callback, and closes the socket.
 * @param bridgeScript Optional path to the bridge script.
 * @param fn The callback to run with the connected socket.
 */
async function WithBridge(bridgeScript: string | undefined, fn: (socket: WebSocket) => Promise<void>): Promise<void> {
    const socket = await EnsureBridge(Config.cliPort, bridgeScript);
    try {
        await fn(socket);
    } finally {
        socket.close();
    }
}

/**
 * Parses and validates an explicit session id string against the list of active sessions.

View on GitHub (pinned to 0592b347b8)

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.

Example fix

// before
await EnsureBridge(48620); // bridge never starts, port blocked
// after
const port = await findFreePort(48620);
await EnsureBridge(port, { retries: 20, retryDelayMs: 500 }); // more patience + known-free port

Defensive patterns

Strategy: retry

Validate before calling

async function bridgeReachable(port: number): Promise<boolean> {
  try {
    const res = await fetch(`http://127.0.0.1:${port}/health`);
    return res.ok;
  } catch { return false; }
}

Try / catch

try {
  await EnsureBridge(port);
} catch (e) {
  if (e instanceof Error && e.message.startsWith("Unable to connect to the Inspector bridge")) {
    console.error(`Bridge on port ${port} unreachable. Check bridge logs / port availability.`);
    process.exitCode = 2;
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: ECONNREFUSED and "connection refused" / "could not connect to server" errors: what they mean and how to fix them — this error's family across 44 libraries.

Related errors

AI-assisted analysis of BabylonJS/Babylon.js@0592b347b8 (2026-08-30). Data as JSON: /api/errors/0d492f4ff9f15599. Report an issue: GitHub.