Errors and close codes

This page lists every failure mode the library can surface, together with what the library does about it and what you can do about it as an operator.

• Parser errors
• Close codes (RFC 6455 §7.4)
• Handshake errors (HTTP/1.1)
• Handshake errors (HTTP/2 / HTTP/3)
• Transport errors

Parser errors

ws_frame:parse/2 returns {error, Reason, Parser}. The session turns each one into the mandated RFC 6455 close frame, sends it, and shuts the socket down. Your handler's terminate/2 receives normal.

Close codes (RFC 6455 §7.4)

The ws_close module gates which codes are legal on the wire.

1> ws_close:valid_on_wire(1000).
true
2> ws_close:valid_on_wire(1005).
false                             %% reserved: "no status"
3> ws_close:reason_name(1009).
message_too_big

Handshake errors (HTTP/1.1)

ws_h1_upgrade:validate_request/1,2 returns {error, Reason} on any of these:

ws_h1_upgrade:validate_response/2 returns {error, Reason} for the client-side validation of a 101:

Additionally ws_client:connect/2 returns {error, sec_websocket_accept_mismatch} if the computed accept value does not match the server's.

Handshake errors (HTTP/2 / HTTP/3)

ws_h2_upgrade:validate_request/1,2 (and its ws_h3_upgrade alias):

ws_h2_upgrade:client_request/4 returns {error, peer_does_not_allow_connect_protocol} if you try to build an extended-CONNECT request against a peer that did not advertise SETTINGS_ENABLE_CONNECT_PROTOCOL = 1.

Transport errors

Transport I/O errors propagate through the session as {stop, {transport_error, Reason}, State} — the handler's terminate/2 is called with that tuple. The most common are closed (peer went away), timeout (only possible during the client handshake), and {tls_alert, _} when the TLS handshake fails.

If a custom transport does not implement recv/2 and the client needs it, ws_client:connect/2 returns {error, {transport_does_not_support_recv, Mod}}.

Size-limit errors