fix(live-ws): reject on bind failure instead of crashing the process (closes #6324)

[vinayakkulkarni]

Summary

The published omniroute standalone image (3.8.45) crash-loops on startup when API_PORT=20129 is set (the documented value), taking the whole gateway down with a 503. This makes startLiveDashboardServer() degrade gracefully on a bind failure instead of crashing the process.

Root cause

3.8.45 wired the live-dashboard WebSocket daemon into the standalone runtime (the await import("@/server/ws/liveServer") added to instrumentation-node.ts, #6202). That import fires the module-level auto-start, which binds LIVE_WS_PORT (default 20129). But 20129 is also the API bridge's port when API_PORT=20129 — so the second listener fails with EADDRINUSE:

[API Bridge] Listening on 0.0.0.0:20129 -> dashboard:20128
Error: listen EADDRINUSE: address already in use 127.0.0.1:20129
⨯ uncaughtException:  Error: listen EADDRINUSE: address already in use 127.0.0.1:20129

startLiveDashboardServer() called server.listen() with no error handler, so the bind failure surfaced as an uncaughtException and crash-looped the container. This is the opposite of the graceful degradation already implemented in apiBridgeServer, embedWsProxy, and startHttpProxyServer, which all catch EADDRINUSE and disable just that one aux server.

Verified empirically against the published 3.8.45-web image on linux/arm64: with OMNIROUTE_ENABLE_LIVE_WS=0 the container comes up healthy and serves 200/307, confirming the LiveWS bind is the sole fatal fault.

Fix

Attach a one-shot error handler that rejects the returned promise on bind failure. The module-level auto-start already has a .catch that logs it non-fatally, so the process now survives.

The listener is on the WebSocketServer (wss), not the underlying http.Server: ws re-emits the server's error via wss.emit("error", …), which throws synchronously when wss has no listener — before any server.on("error") handler could run. (A server.on("error") handler looks correct but does not catch it; confirmed with a minimal repro.)

Related Issues

• Closes fix(docker): 3.8.45-web crash-loops on startup — LiveWS double-binds 20129 (EADDRINUSE) + corrupt Next.js chunk #6324

Validation

• npm run lint (eslint on changed files — clean)
• npm run test:unit (new test + existing live-ws suite: 34/34 pass)
• npm run test:coverage (not run locally — full-suite coverage; CI will run it)
• Coverage: the changed branch (bind-failure path) is now covered by the new test (previously uncovered)
• SonarQube PR analysis (runs in CI)

Typecheck (tsc -p tsconfig.typecheck-core.json) is also clean.

Red/green proof: with the fix reverted, the new test fails with a raw EADDRINUSE; with the fix, it passes.

Tests Added Or Updated

• tests/unit/live-ws-eaddrinuse-6324.test.ts (new) — occupies the target port first, then asserts startLiveDashboardServer() rejects with EADDRINUSE instead of crashing.

Coverage Notes

• Touches src/server/ws/liveServer.ts. The new test exercises the added bind-failure rejection path; the happy path is already covered by tests/integration/live-ws-startup.test.ts.

Reviewer Notes

• No behavior change on the success path — only the previously-unhandled failure path changes (crash → logged, non-fatal).
• This addresses the runtime crash of the already-published 3.8.45-web image. A second, non-fatal log-only error also appears in that image on startup — Error: file data stream has unexpected number of bytes at .build/next/server/chunks/_099ro22._.js — but it does not stop the server (verified: container serves 200 with LiveWS disabled). It looks like a build-artifact issue rather than a source defect, so it's intentionally out of scope for this PR; happy to open a separate issue if useful.

[gemini-code-assist]

Code Review

This pull request addresses issue #6324 by modifying startLiveDashboardServer in src/server/ws/liveServer.ts to gracefully handle port bind failures (such as EADDRINUSE) instead of crashing the process. It now returns a Promise that rejects upon encountering a WebSocket server error, cleaning up event subscriptions and clients in the process. Additionally, a new unit test file tests/unit/live-ws-eaddrinuse-6324.test.ts has been added to verify this behavior by simulating a port conflict. No review comments were provided, so I have no feedback to offer.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[diegosouzapw]

Merged — thank you, @vinayakkulkarni! Great catch on attaching the error listener to wss (not server) and releasing the EventBus subscription on a failed start. Added a CHANGELOG bullet; regression guard tests/unit/live-ws-eaddrinuse-6324.test.ts (1/1 local). Integrated into release/v3.8.46.