WebSocket: Received network error or non-101 status code

[rkistner]

Bug Description

WebSocket connection errors display a generic Received network error or non-101 status code. error on any connection issue, whether the underlying cause is connection refused, TLS error, protocol upgrade error, or any other issue.

I'm not sure if this is by design, but this makes debugging the issue or displaying an appropriate error to the user difficult.

Reproducible By

import { WebSocket } from 'undici';

// No actual server here
const ws = new WebSocket('ws://localhost:1234');

ws.addEventListener('error', (event) => {
  console.log('error', event.error);
});

Expected Behavior

The error should clearly indicate the cause.

Logs & Screenshots

Error: Received network error or non-101 status code.
    at #onFail (<myproject>/node_modules/undici/lib/web/websocket/websocket.js:469:16)
    at Object.onFail (<myproject>/node_modules/undici/lib/web/websocket/websocket.js:63:43)
    at failWebsocketConnection (<myproject>/node_modules/undici/lib/web/websocket/connection.js:318:11)
    at Object.processResponse (<myproject>/node_modules/undici/lib/web/websocket/connection.js:108:9)
    at <myproject>/node_modules/undici/lib/web/fetch/index.js:1072:19

Environment

Node v24.1.0, undici 7.10.0.

Additional context

My current workaround is to create a custom Dispatcher that records the underlying error. This actually works quite well, and indicates that the underlying cause is available, just not exposed. See the implementation here:
https://gist.github.com/rkistner/a9a000ed584a93c7641272420e8334e7

For reference, I'm using undici instead of the ws package since the Dispatcher support is great - I get much better control over TLS options over a proxy connection.

See more examples of users getting this error here: #3836

[Ethan-Arrowood]

I support this change, are you interested in submitting a pull request? If you do, make sure to include tests and documentation too

[rkistner]

I'm not sure when I'll have time, but I could look into that later.

Is there any kind of standard or convention for what the errors should look like? For example, would it be fine to just include the upstream error directly on event.error? I don't see any details on errors in the whatwg/websockets spec - I think browsers deliberately don't include any details on connection errors.

[KhafraDev]

Is there any kind of standard or convention for what the errors should look like?

You could add it as a cause where the error is created.

undici/lib/web/websocket/websocket.js

Line 469 in 8b1c093

error: new Error(reason),

[Ethan-Arrowood]

I would recommend investigating what the major browsers do for this type of error. You can also check out the spec to see if maybe its something we missed in the implementation. I'm all for including more error information, but being consistent with other WS implementations is key too.

[KhafraDev]

We do the same thing in fetch already.

[rkistner]

What I've found so far:

1. The whatwg/websockets spec mentions almost nothing on the error event format.
2. I tested Chrome and Firefox - neither include any details on the error event. This appears to be intentional for browsers: Connection status code whatwg/websockets#21 (comment)
3. The close event does include a code, but this is very limited for identifying connection issues. In practice I just see 1005 or 1006 for connection failures.
4. React Native includes a event.message directly on the error event, but no Error object.
5. The ws package includes the upstream error in event.error, and a copy of the message on event.message.

Personally I'm happy with either using the upstream error directly, or setting it as error.cause.

[KhafraDev]

It should be set as the cause.

[rkistner]

@KhafraDev Thanks for the fix - I tested this in v7.11.0 now, and it works great!