headroomlabs-ai/headroom · error · ValueError

Unsupported Content-Encoding: {encoding}

Error message

Unsupported Content-Encoding: {encoding}

What it means

Error "Unsupported Content-Encoding: {encoding}" thrown in headroomlabs-ai/headroom.

Source

Thrown at headroom/proxy/helpers.py:2438

        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
    elif encoding and encoding != "identity":
        raise ValueError(f"Unsupported Content-Encoding: {encoding}")

    return cast(bytes, raw)


# ---------------------------------------------------------------------------
# Output-only content blocks
# ---------------------------------------------------------------------------
# The Anthropic *response* schema can emit signaling blocks that the *request*
# schema (messages[].content[]) does not accept. The primary case is the
# server-side refusal fallback notification introduced with the
# ``server-side-fallback-2026-06-01`` beta::
#
#     {"type": "fallback",
#      "from": {"model": "claude-fable-5"},
#      "to":   {"model": "claude-opus-4-8"}}
#
# The API returns it inside an assistant turn to signal that a refused request
# was transparently re-served by the fallback model. When a client replays that

View on GitHub (pinned to 322425c43b)

Solutions

1. Send the request body with a supported Content-Encoding: identity, gzip, deflate, br, or zstd
2. Remove or fix the unsupported Content-Encoding header '{encoding}' on the client
3. If the encoding is legitimate but unsupported, decode it client-side before proxying

When it happens

Trigger: Raised when a request arrives with a Content-Encoding the proxy does not know how to decompress.

Common situations: See trigger scenarios.

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