aio-libs/aiohttp · error · WSHandshakeError

Extension for deflate not supported

Error message

Extension for deflate not supported{ext.group(1)}

What it means

The client found a `permessage-deflate` token in the server's `Sec-WebSocket-Extensions` header, but its parameter list did not match the expected grammar (`_WS_EXT_RE` in `helpers.py`). Because the client offered compression and the server's response is malformed or carries unsupported parameters, the handshake fails with `WSHandshakeError` (surfaced as `WSServerHandshakeError`).

Solutions

  1. Retry the connection without compression: `ws_connect(url, compress=0)`.
  2. If you control the server, send only the four recognized parameters with correct `; `-separated syntax.
  3. Wrap `ws_connect` in try/except `WSServerHandshakeError` and degrade to uncompressed WS.

Example fix

# before
ws = await session.ws_connect(url, compress=15)  # server params failed to parse -> error
# after
try:
    ws = await session.ws_connect(url, compress=15)
except aiohttp.WSServerHandshakeError:
    ws = await session.ws_connect(url, compress=0)
Defensive patterns

Strategy: fallback

Try / catch

try:
    ws = await session.ws_connect(url, compress=15)
except aiohttp.WSServerHandshakeError:
    ws = await session.ws_connect(url, compress=0)

Prevention

When it happens

Trigger: Client requests compression; server replies with `Sec-WebSocket-Extensions: permessage-deflate; <params>` where `<params>` fails `_WS_EXT_RE` — e.g. unknown parameters, bad separators, or an unexpected parameter form. `ws_ext_parse(..., isserver=False)` raises at `helpers.py:124`.

Common situations: A non-standard server/proxy adds unsupported deflate parameters; a CDN rewrites the extension header; the server emits parameters the regex doesn't accept (only `server_no_context_takeover`, `client_no_context_takeover`, `server_max_window_bits`, `client_max_window_bits` are recognized).

Related errors

AI-assisted analysis of aio-libs/aiohttp@d041d4d0fd (2026-08-11). Data as JSON: /api/errors/a9205b42f60898f4. Report an issue: GitHub.

Appendix: source

Thrown at aiohttp/_websocket/helpers.py:124

                    notakeover = True
                # Ignore regex group 5 & 6 for client_max_window_bits
                break
            else:
                if match.group(6):
                    compress = int(match.group(6))
                    # Group5 must match if group6 matches
                    # Compress wbit 8 does not support in zlib
                    # If compress level not support,
                    # FAIL the parse progress
                    if compress > 15 or compress < 9:
                        raise WSHandshakeError("Invalid window size")
                if match.group(2):
                    notakeover = True
                # Ignore regex group 5 & 6 for client_max_window_bits
                break
        # Return Fail if client side and not match
        elif not isserver:
            raise WSHandshakeError("Extension for deflate not supported" + ext.group(1))

    return compress, notakeover


def ws_ext_gen(
    compress: int = 15, isserver: bool = False, server_notakeover: bool = False
) -> str:
    # client_notakeover=False not used for server
    # compress wbit 8 does not support in zlib
    if compress < 9 or compress > 15:
        raise ValueError(
            "Compress wbits must between 9 and 15, zlib does not support wbits=8"
        )
    enabledext = ["permessage-deflate"]
    if not isserver:
        enabledext.append("client_max_window_bits")

    if compress < 15:

View on GitHub (pinned to d041d4d0fd)