Exceptions

websockets.exceptions defines the following hierarchy of exceptions.

• WebSocketException

  • ConnectionClosed

    • ConnectionClosedOK

    • ConnectionClosedError

  • InvalidURI

  • InvalidHandshake

    • SecurityError

    • InvalidMessage

    • InvalidStatus

    • InvalidStatusCode (legacy)

    • InvalidHeader

      • InvalidHeaderFormat

      • InvalidHeaderValue

      • InvalidOrigin

      • InvalidUpgrade

    • NegotiationError

      • DuplicateParameter

      • InvalidParameterName

      • InvalidParameterValue

    • AbortHandshake (legacy)

    • RedirectHandshake (legacy)

  • ProtocolError (Sans-I/O)

  • PayloadTooBig (Sans-I/O)

  • InvalidState (Sans-I/O)

  • ConcurrencyError

exception websockets.exceptions.WebSocketException

Base class for all exceptions defined by websockets.

Connection closed

recv(), send(), and similar methods raise the exceptions below when the connection is closed. This is the expected way to detect disconnections.

exception websockets.exceptions.ConnectionClosed(rcvd, sent, rcvd_then_sent=None)

Raised when trying to interact with a closed connection.

rcvd

If a close frame was received, its code and reason are available in rcvd.code and rcvd.reason.

sent

If a close frame was sent, its code and reason are available in sent.code and sent.reason.

rcvd_then_sent

If close frames were received and sent, this attribute tells in which order this happened, from the perspective of this side of the connection.

exception websockets.exceptions.ConnectionClosedOK(rcvd, sent, rcvd_then_sent=None)

Like ConnectionClosed, when the connection terminated properly.

A close code with code 1000 (OK) or 1001 (going away) or without a code was received and sent.

exception websockets.exceptions.ConnectionClosedError(rcvd, sent, rcvd_then_sent=None)

Like ConnectionClosed, when the connection terminated with an error.

A close frame with a code other than 1000 (OK) or 1001 (going away) was received or sent, or the closing handshake didn’t complete properly.

Connection failed

These exceptions are raised by connect() when the opening handshake fails and the connection cannot be established. They are also reported by serve() in logs.

exception websockets.exceptions.InvalidURI(uri, msg)

Raised when connecting to a URI that isn’t a valid WebSocket URI.

exception websockets.exceptions.InvalidHandshake

Base class for exceptions raised when the opening handshake fails.

exception websockets.exceptions.InvalidMessage

Raised when a handshake request or response is malformed.

exception websockets.exceptions.SecurityError

Raised when a handshake request or response breaks a security rule.

Security limits can be configured with environment variables.

exception websockets.exceptions.InvalidStatus(response)

Raised when a handshake response rejects the WebSocket upgrade.

exception websockets.exceptions.InvalidHeader(name, value=None)

Raised when an HTTP header doesn’t have a valid format or value.

exception websockets.exceptions.InvalidHeaderFormat(name, error, header, pos)

Raised when an HTTP header cannot be parsed.

The format of the header doesn’t match the grammar for that header.

exception websockets.exceptions.InvalidHeaderValue(name, value=None)

Raised when an HTTP header has a wrong value.

The format of the header is correct but the value isn’t acceptable.

exception websockets.exceptions.InvalidOrigin(origin)

Raised when the Origin header in a request isn’t allowed.

exception websockets.exceptions.InvalidUpgrade(name, value=None)

Raised when the Upgrade or Connection header isn’t correct.

exception websockets.exceptions.NegotiationError

Raised when negotiating an extension or a subprotocol fails.

exception websockets.exceptions.DuplicateParameter(name)

Raised when a parameter name is repeated in an extension header.

exception websockets.exceptions.InvalidParameterName(name)

Raised when a parameter name in an extension header is invalid.

exception websockets.exceptions.InvalidParameterValue(name, value)

Raised when a parameter value in an extension header is invalid.

Sans-I/O exceptions

These exceptions are only raised by the Sans-I/O implementation. They are translated to ConnectionClosedError in the other implementations.

exception websockets.exceptions.ProtocolError

Raised when receiving or sending a frame that breaks the protocol.

The Sans-I/O implementation raises this exception when:

• receiving or sending a frame that contains invalid data;

• receiving or sending an invalid sequence of frames.

exception websockets.exceptions.PayloadTooBig(size_or_message, max_size=None, cur_size=None)

Raised when parsing a frame with a payload that exceeds the maximum size.

The Sans-I/O layer uses this exception internally. It doesn’t bubble up to the I/O layer.

The decode() method of extensions must raise PayloadTooBig if decoding a frame would exceed the limit.

exception websockets.exceptions.InvalidState

Raised when sending a frame is forbidden in the current state.

Specifically, the Sans-I/O layer raises this exception when:

• sending a data frame to a connection in a state other OPEN;

• sending a control frame to a connection in a state other than OPEN or CLOSING.

Miscellaneous exceptions

exception websockets.exceptions.ConcurrencyError

Raised when receiving or sending messages concurrently.

WebSocket is a connection-oriented protocol. Reads must be serialized; so must be writes. However, reading and writing concurrently is possible.

Legacy exceptions

These exceptions are only used by the legacy asyncio implementation.

exception websockets.exceptions.InvalidStatusCode(status_code, headers)

Raised when a handshake response status code is invalid.

exception websockets.exceptions.AbortHandshake(status, headers, body=b'')

Raised to abort the handshake on purpose and return an HTTP response.

This exception is an implementation detail.

The public API is process_request().

status

HTTP status code.

Type:

HTTPStatus

headers

HTTP response headers.

Type:

Headers

body

HTTP response body.

Type:

bytes

exception websockets.exceptions.RedirectHandshake(uri)

Raised when a handshake gets redirected.

This exception is an implementation detail.