headroomlabs-ai/headroom · error · ValueError

Request body is zstd-compressed but the 'zstandard' package

Error message

Request body is zstd-compressed but the 'zstandard' package is not installed. Install it with: pip install zstandard

What it means

Error "Request body is zstd-compressed but the 'zstandard' package is not installed. Install it with: pip install zstandard" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/helpers.py:2406

    """Read and (if needed) decompress the request body, returning raw UTF-8 bytes.

    Mirrors ``_read_request_json`` but returns the bytes pre-parse so
    forwarders can implement byte-faithful passthrough (PR-A3, fixes P0-2).
    Raises ``ValueError`` on any decompression failure.
    """
    encoding = (request.headers.get("content-encoding") or "").lower().strip()
    raw = await request.body()

    if encoding in ("zstd", "zstandard"):
        try:
            import zstandard

            dctx = zstandard.ZstdDecompressor()
            reader = dctx.stream_reader(raw)
            raw = reader.read()
            reader.close()
        except ImportError:
            raise ValueError(
                "Request body is zstd-compressed but the 'zstandard' package is not installed. "
                "Install it with: pip install zstandard"
            ) from None
        except Exception as exc:
            raise ValueError(f"Failed to decompress zstd request body: {exc}") from exc
    elif encoding == "gzip":
        import gzip as _gzip

        try:
            raw = _gzip.decompress(raw)
        except Exception as exc:
            raise ValueError(f"Failed to decompress gzip request body: {exc}") from exc
    elif encoding == "deflate":
        import zlib

        try:
            raw = zlib.decompress(raw)
        except Exception as exc:

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the zstandard package: pip install zstandard
2. Or ask the client to send the body uncompressed or with an encoding you support (identity/gzip)
3. If you control the client, remove `Content-Encoding: zstd` from the request

When it happens

Trigger: Raised when the proxy receives a request body with Content-Encoding: zstd but the optional `zstandard` package is not installed, so the body cannot be decompressed.

Common situations: See trigger scenarios.

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/62aa9eae02678db8. Report an issue: GitHub.