[nissa-seru]

A transport error with nothing listening for it is now logged instead of thrown, at both places where one could end the process: on an McplServerConnection with no 'error' listener, and on a transport before the handshake attaches its listener. The second ended framework hosts too. A WebSocket MCPL server that sent a malformed frame with its upgrade response ended the host connecting to it. !Fixes #391.

Problem

• A bare connection (A bare McplServerConnection throws on any transport error when nothing listens for 'error' #391). setupLifecycle passed every transport error on as the connection's own 'error', with no listener check. EventEmitter throws an 'error' that nothing listens for. A transport reports its errors from I/O callbacks, where nothing catches that throw, so it ended the process. The framework always attaches an 'error' listener, so hosts weren't affected. But McplServerConnection is exported (src/index.ts), and a probe, a playtest or a harness holding one often attaches none. In a probe on main 91e70eda, a separate process holding a bare WebSocket connection died with Unhandled 'error' event when its server sent a frame with a reserved opcode.
• A transport before the handshake listens. This reaches further than A bare McplServerConnection throws on any transport error when nothing listens for 'error' #391, since it ends framework hosts. WebSocketTransport passed ws's 'error' on with no listener check. ws's setSocket unshifts any bytes that came with the 101 upgrade response before it emits 'open', and the connection constructs the transport in that 'open' handler. ws raises a bad frame's error on a nextTick, and Node runs nextTick callbacks before the promise continuation where handshake() attaches its listener. So a server that sends a malformed frame with its upgrade response ends the process that's connecting, before any listener of the framework's exists. With main's src/mcpl/ at 0d19f7c8, the fixture test/fixtures/mcpl-ws-upgrade-error-probe.mjs exits with Unhandled 'error' event and RangeError: Invalid WebSocket frame: invalid opcode 3. StdioTransport passed the child's own 'error' on the same way, though we found nothing that triggers it in that window.

Changes

• McplTransport.reportError gives a transport error to the transport's 'error' listeners when it has any, and otherwise logs [mcpl] <server>: a <stdio|websocket> transport error, with nothing listening for it: <message>. ws's 'error', the stdio child's own 'error' and a read error on the child's stderr all go through it. Since fix(mcpl): SIGTERM a stdio child whose stdin or stdout fails #384, an error on the child's stdin or stdout ends the transport through the exit's close and emits nothing, so this change leaves those as they are. stderr's read-error listener used to emit only when something listened, and dropped the error otherwise.
• Each transport keeps its server's id from the config, as an optional constructor argument, so that line names the server.
• McplServerConnection.emitToErrorListeners, one private helper, gives an error to the connection's 'error' listeners if it has any, and says whether it had. It catches and logs a listener that throws, with the error that listener was handling: [mcpl] <server>: an 'error' listener failed: <its failure>, handling <the error>. Both places the connection emits 'error' use it: fix(mcpl): contain inbound request handler failures #208's reportInboundFailure, which carried the check inline, and the transport-error forwarder, which carried none (A bare McplServerConnection throws on any transport error when nothing listens for 'error' #391).
• A transport error with no connection listener is logged as [mcpl] <server>: transport error: <message>. With a listener, the listener gets the same Error as before, and nothing is logged. reportInboundFailure logs its own line as before, and hands its error to the helper.
• Changelog fragment 391-transport-error-no-listener.fixed.md.

What each part is for

• reportError keeps a transport from ending the process in the window before the handshake attaches its listener, the window in which framework hosts ended. It's one protected method on the base class, used by the three forwarders.
• The server's id in its line. In a host with several servers, a line that names none can't be acted on, and before the handshake listens that line is the only record of the error. The argument is optional so that a test's stand-in transport constructs as before.
• emitToErrorListeners puts one rule where the connection emitted 'error' in two ways. It catches a throwing listener because that throw would come from an I/O callback too, where nothing catches it.
• The log line for a transport error with no connection listener is what a bare connection's holder sees in place of the crash.
• Not kept. This change had a process test of a bare WebSocket connection, with its fixture mcpl-bare-ws-error-probe.mjs. Every piece below that it caught, another test catches, so the last commit takes it out. The upgrade probe's process test stays, since it runs ws's own order of events at upgrade, which the fix is for.

What a deployment will notice

• A WebSocket server that sends a malformed frame with its upgrade response no longer ends the host. The error is logged with the server's id, and the connect is refused. ws reads nothing more once it has failed the connection, so the refusal comes when the server closes the connection, as a WebSocket server does after answering the close frame ws sends. In the fixture's runs at this head, the refusal came in 11 to 14 ms over three runs when the server closes (transport closed before handshake completed (websocket closed, code 1006)), and in about 30 s when it never does, where ws's close timeout and the handshake's own timeout, both 30 s, race. In two such runs, the handshake's timeout ended one (initialize handshake timed out, 30,014 ms) and ws's close ended the other (30,018 ms). The connection retries a server set to reconnect, as it does any connect that fails before its handshake (test/mcpl-reconnect-events.test.ts).
• A read error on a stdio child's stderr with nothing listening is logged, where it was dropped. It ends nothing.
• Nothing else changes for a host the framework wires. A transport error is still traced as mcpl:server-error.
• A tool holding a bare connection survives a transport error, and logs it. After a WebSocket error, ws closes the socket, and the connection's 'close' follows. A stdio child's own 'error', or a read error on its stderr, leaves the link up, and the connection only logs it.

Tests

test/mcpl-transport-error-listeners.test.ts:

• The no-listener test. With no 'error' listener on the connection, a transport error doesn't throw and is logged.
• The listener test. With one, the listener gets the error and nothing is logged. It's a control, which main passes too.
• The throwing-listener test. A listener that throws on a transport error is caught and logged, with the error it was handling.
• The stand-in transports test. A stand-in child, its stderr and a stand-in socket each emit 'error' with nothing listening on their transport. Nothing is thrown, all three are logged with their server's id, and once listeners attach they get the errors.
• The upgrade process test. A separate process connecting to a server that sends that frame with its upgrade response, then answers ws's close frame and ends the connection (fixture mcpl-ws-upgrade-error-probe.mjs), is refused, logs the error with the server's id, and exits 0.

Runs at ce33bfb0's tree, on Linux with Node 24.22.0:

• tsc --noEmit is clean. This file, test/mcpl-request-handler-errors.test.ts, mcpl-transport-close.test.ts and mcpl-ws-transport.test.ts pass 109 of 109.

• Red-first. With main's src/mcpl/server-connection.ts and src/mcpl/transport.ts at 0d19f7c8 and these tests, the 4 that aren't the control fail.

• Each piece. Taking out each of twelve pieces on its own fails at least one test:

  Piece taken out	Caught by
  reportError's listener check (it always emits)	the stand-in transports test, the upgrade process test, and fix(mcpl): SIGTERM a stdio child whose stdin or stdout fails #384's stderr read-error test
  reportError's log line	the stand-in transports test, and the upgrade process test
  the server's id in reportError's line	the stand-in transports test, and the upgrade process test
  reportError in the ws 'error' forwarder (a plain emit instead)	the stand-in transports test, and the upgrade process test
  reportError in the child 'error' forwarder (a plain emit instead)	the stand-in transports test
  reportError in the stderr read-error listener (an emit only when something listens)	the stand-in transports test
  the helper's listener check	the no-listener test
  the log line for a transport error with no listener	the no-listener test
  the helper's catch of a throwing listener	the throwing-listener test, and fix(mcpl): contain inbound request handler failures #208's test of a throwing 'error' listener
  the error being handled, in the listener-failed line	the throwing-listener test
  reportInboundFailure handing its error to the helper	8 of fix(mcpl): contain inbound request handler failures #208's tests
  the same, with a plain emit in its place	fix(mcpl): contain inbound request handler failures #208's test of a throwing 'error' listener, and its separate stdio host in throwing-listener mode

CI runs the typecheck, the build and the suite on this pull request.

Not verified

• No real MCPL server. The servers here are the tests' own scripts, and we ran no server in the ecosystem against this.
• A connect to a server that never closes the connection after ws's close frame waits about 30 s before it's refused, until ws's close timeout or the handshake's own timeout ends it. This change doesn't shorten that wait, and the suite doesn't run that case, since it would hold a test for 30 s. The two runs above are the fixture run by hand.

Merge notes

• feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262 and feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337 conflict with this change in src/mcpl/transport.ts. feat(mcp): modern MCP (2026-07-28) servers beside MCPL, over stdio and Streamable HTTP #262 also gives StdioTransport the server's id, as its first argument where this change adds it last, and adds an import beside the one this change restores. Their resolution keeps one argument order. feat(mcp): MCP servers on the 2025 revisions over Streamable HTTP #337 already conflicts with main in that file, and its conflicts there also hold this change's reportError forwarders.

---

• Changelog fragment added — changelog.d/391-transport-error-no-listener.fixed.md

Written by Tabitha-2696 (Claude Opus 5.5), contributing through nissa-seru. Ada-1017 made the design calls. Our internal review of the first commit found the upgrade case, which the second answers, and its review of the second found the line naming no server, which the fourth answers. Ramona-2416 (Claude Opus 5.5) reviewed it across its rounds, and read it again after its rebase onto main.

🤖 Written with Claude Opus 5.5 through the Rookery's Pi tooling.

Description checked and posted by Fiona-2757 (Claude Opus 5.5).

[greptile-apps]

Required label not found on this PR.