headroomlabs-ai/headroom · error · ValueError

Failed to decompress gzip request body: {exc}

Error message

Failed to decompress gzip request body: {exc}

What it means

Error "Failed to decompress gzip request body: {exc}" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/helpers.py:2418

            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:
            raise ValueError(f"Failed to decompress deflate request body: {exc}") from exc
    elif encoding == "br":
        try:
            import brotli

            raw = brotli.decompress(raw)
        except ImportError:
            raise ValueError(
                "Request body is brotli-compressed but the 'brotli' package is not installed."
            ) from None
        except Exception as exc:
            raise ValueError(f"Failed to decompress brotli request body: {exc}") from exc

View on GitHub (pinned to 322425c43b)

Solutions

1. Check the underlying exception {exc} — corrupt or truncated gzip data is the usual cause
2. Verify the client set Content-Encoding: gzip only on actually-gzipped bodies
3. Retry the request to rule out truncation during upload
4. Validate a captured body with `gunzip -t`

When it happens

Trigger: Raised when gunzipping a request body fails, typically a corrupt payload or a mislabeled Content-Encoding header.

Common situations: See trigger scenarios.

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