Server process exits on connect timeout: ws.terminate() on a CONNECTING socket -> uncaughtException -> process.exit(1)

[LootGoblin]

Summary

Whenever the Unity WebSocket handshake fails to complete within connectTimeout (5s), the Node server process exits, closing the stdio pipe. From the MCP client's side the entire tool surface disappears mid-session (MCP error -32000: Connection closed).

The package already implements reconnection with exponential backoff — it never gets a chance to run, because the process is dead before the first retry.

Reproduced on 1.2.0 and 1.3.0 (c35f184) — Node v24.16.0, Windows 11, Unity 6.

Root cause

UnityConnection.doConnect() sets a connect-timeout timer:

this.connectionTimeoutTimer = setTimeout(() => {
  if (this.ws && this.ws.readyState === WebSocket.CONNECTING) {
    this.closeWebSocket('Connection timeout');
    ...
  }
}, this.config.connectTimeout);

closeWebSocket() clears the error handler, then terminates:

socket.onerror = null;        // <-- removes the only 'error' listener
...
try {
  socket.terminate();         // <-- socket is still CONNECTING
} catch (err) { ... }

ws.terminate() on a CONNECTING socket calls abortHandshake(), which emits 'error'. Because onerror was just cleared there is no listener, so Node's EventEmitter throws. The throw originates in a timer tick, so the surrounding try/catch cannot catch it:

Error: WebSocket was closed before the connection was established
    at WebSocket.terminate (node_modules/ws/lib/websocket.js:489:7)
    at UnityConnection.closeWebSocket (build/unity/unityConnection.js:396:20)
    at Timeout.<anonymous> (build/unity/unityConnection.js:174:26)
    at listOnTimeout (node:internal/timers:605:17)

It surfaces as an uncaughtException, and index.ts treats anything that isn't EPIPE/EOF/ERR_USE_AFTER_CLOSE as fatal:

serverLogger.error('Uncaught exception', error);
process.exit(1);

Why it's hard to spot

utils/logger.ts discards all output unless LOGGING=true or LOGGING_FILE=true. With neither set — the default when an MCP client launches the server over stdio — the crash reason goes to a no-op logger and the process dies completely silently. I only got the stack by re-running with LOGGING_FILE=true plus my own uncaughtException handler.

Reproduction

1. Put the Unity bridge in a state where it accepts TCP but doesn't complete the handshake — e.g. a busy editor, or the wedged-listener state in Failed to start WebSocket server: Port <PORT NUMBER> is already in use #141.
2. node Server~/build/index.js
3. Exits with code 1 after ~5s, printing nothing.

In normal use the trigger is routine: any domain reload that outlasts the 5s connect timeout.

Suggested fix

Keep an error listener attached so abortHandshake's emit has somewhere to land:

socket.onopen = null;
socket.onmessage = null;
socket.onclose = null;
socket.removeAllListeners('pong');
socket.onerror = () => {};   // terminate() on a CONNECTING socket emits 'error';
                             // an EventEmitter with no 'error' listener throws.
try { socket.terminate(); } catch (err) { ... }

Worth considering alongside it: a fault originating in the Unity connection is recoverable by design, given the reconnect machinery already present. Treating every such fault as fatal turns a transient editor hiccup into a lost session. Downgrading connection-class faults to a warning would make the existing backoff logic actually reachable.

Workaround

A small launcher that imports the server and then replaces its process-level handlers with tolerant ones. With that in place, a single server process survived two bridge outages (including the #141 wedge) and three Unity restarts in one session, reconnecting each time, with no loss of tools.

Related: #141 — that issue is the Unity-side cause of the timeouts; this issue is about the client-side reaction to them being fatal.

[CoderGamester]

Confirmed against the MCP Unity 1.4.0 tag: this remains a valid legacy-bridge defect.

The tagged Node connection code still clears socket.onerror before calling terminate() on a potentially CONNECTING WebSocket, so the reported abortHandshake() error can still escape as an uncaught exception. The final 1.4.0 Unity lifecycle fixes do not change that Node teardown path.

Keeping this issue open as a known 1.4.x limitation. PR #154 removes UnityConnection, the Node WebSocket client, reconnect backoff, and the custom bridge in 2.0.0. After 2.0.0 ships, this can be closed as resolved by the architecture replacement unless a separate Unity CLI transport problem is reproduced.

[TenaciousLibbs]

Confirming this independently — we hit the same chain in a fork and shipped exactly the fix you propose.

Two details worth adding, both of which cost us time:

1. The stack trace is misleading. abortHandshake builds the Error synchronously, so the stack points at closeWebSocket — but it emits on process.nextTick. That is why the surrounding try/catch never sees it, and why the obvious reading of the trace sends you to the wrong place.

2. Why the uncaughtException guard misses it: the error has no .code property at all (code=undefined), so the EPIPE / EOF / ERR_USE_AFTER_CLOSE check in index.ts cannot match and it falls straight through to process.exit(1).

Reproducible without Unity: point a ws client at a TCP listener that accepts the connection but never speaks WebSocket (this holds it in CONNECTING, the same state as an Editor mid-domain-reload), then run the closeWebSocket sequence. On ws@8.18.1 / Node 24:

unfixed                 exit=1   WebSocket was closed before the connection was established (code=undefined)
socket.onerror = noop   exit=0   survives, reconnect proceeds

Confirmed still present on main as of 2026-08-02.

Opened #155 with the one-line fix. npm run build and npm test both pass on that branch (11 suites / 117 tests).