aio-libs/aiohttp · error · ValueError

compress must be one of True, False, 'deflate', or 'gzip'

Error message

compress must be one of True, False, 'deflate', or 'gzip'

What it means

Raised by ClientRequest._update_content_encoding() when the 'compress' parameter is a string that is neither 'deflate' nor 'gzip'. aiohttp supports only those two algorithms for request body compression; any other string value (e.g. 'br', 'zstd') is rejected with ValueError. Non-string truthy values (True) default to 'deflate' and do not trigger this.

Solutions

1. Use one of the supported values: compress=True (deflate), compress='deflate', or compress='gzip'.
2. Note values are case-sensitive — use lowercase 'gzip'/'deflate'.
3. If you need Brotli/zstd for requests, compress the body yourself and set Content-Encoding manually (then don't pass compress).
4. Validate config-driven compress strings against {'deflate','gzip'}.

Example fix

# before
await session.post(url, data=body, compress='br')  # ValueError

# after
await session.post(url, data=body, compress='gzip')

def normalize_compress(compress):
    if compress is True:
        return 'deflate'
    if compress is False or compress is None:
        return None
    if isinstance(compress, str) and compress.lower() in ('deflate', 'gzip'):
        return compress.lower()
    raise ValueError(f"compress must be True, False, 'deflate', or 'gzip', got {compress!r}")

def is_supported_compress(compress) -> bool:
    return compress in (True, False, None) or (isinstance(compress, str) and compress.lower() in ('deflate', 'gzip'))

try:
    await session.post(url, data=body, compress=compress)
except ValueError as e:
    if 'compress must be one of' in str(e):
        await session.post(url, data=body, compress='gzip')  # safe default
    else:
        raise

When it happens

Trigger: Calling session.post(url, data=body, compress='br') or compress='zstd'. The isinstance(compress, str) and not-in-{'deflate','gzip'} check fails and raises ValueError.

Common situations: Assuming Brotli/zstd (supported for response decoding) is also supported for request compression; passing a compression name from config without validation; case mismatch ('GZIP' vs 'gzip').

Related errors

• compress can not be set if Content-Encoding header is set
• Invalid Content-Length header
• InvalidURL
• Method cannot contain non-token characters
• aiohttp only supports http(s) proxies

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

Appendix: source

Thrown at aiohttp/client_reqrep.py:1215

        self.headers[hdrs.COOKIE] = c.output(header="", sep=";").strip()

    def _update_content_encoding(
        self, data: Any, compress: bool | Literal["deflate", "gzip"]
    ) -> None:
        """Set request content encoding."""
        self.compress = None
        if not data:
            return

        if self.headers.get(hdrs.CONTENT_ENCODING):
            if compress:
                raise ValueError(
                    "compress can not be set if Content-Encoding header is set"
                )
        elif compress:
            if isinstance(compress, str) and compress not in {"deflate", "gzip"}:
                raise ValueError(
                    "compress must be one of True, False, 'deflate', or 'gzip'"
                )
            self.compress = compress if isinstance(compress, str) else "deflate"
            self.headers[hdrs.CONTENT_ENCODING] = self.compress
            self.chunked = True  # enable chunked, no need to deal with length

    def _update_transfer_encoding(self) -> None:
        """Analyze transfer-encoding header."""
        te = self.headers.get(hdrs.TRANSFER_ENCODING, "").lower()

        if "chunked" in te:
            if self.chunked:
                raise ValueError(
                    "chunked can not be set "
                    'if "Transfer-Encoding: chunked" header is set'
                )

        elif self.chunked:

View on GitHub (pinned to d041d4d0fd)