headroomlabs-ai/headroom · error · ImportError

httpx is required for Headroom Cloud mode: pip install httpx

Error message

httpx is required for Headroom Cloud mode: pip install httpx

What it means

Raised in litellm_callback._cloud_compress(): when Headroom's LiteLLM callback is configured for Cloud mode (managed CCR/TOIN/analytics via the Headroom SaaS API) and the lazy `import httpx` inside the method fails. Headroom makes httpx optional and only imports it when the first cloud compression request is attempted, so the error surfaces at request time, not at callback registration.

Source

Thrown at headroom/integrations/litellm_callback.py:182

            model=model or "claude-sonnet-4-5-20250929",
            model_limit=self._model_limit,
            hooks=self._hooks,
        )
        return {
            "messages": result.messages,
            "tokens_before": result.tokens_before,
            "tokens_after": result.tokens_after,
            "tokens_saved": result.tokens_saved,
            "compression_ratio": result.compression_ratio,
        }

    async def _cloud_compress(self, messages: list[dict], model: str) -> dict[str, Any] | None:
        """Compress via Headroom Cloud API (managed CCR, TOIN, analytics)."""
        if self._client is None:
            try:
                import httpx
            except ImportError as e:
                raise ImportError(
                    "httpx is required for Headroom Cloud mode: pip install httpx"
                ) from e
            self._client = httpx.AsyncClient(timeout=30.0)

        client = self._client
        assert client is not None
        resp = await client.post(
            f"{self._api_url}/v1/saas/compress",
            headers={
                "X-Headroom-Key": self._api_key,
                "Content-Type": "application/json",
            },
            content=json.dumps(
                {
                    "messages": messages,
                    "model": model or "claude-sonnet-4-5-20250929",
                    "model_limit": self._model_limit,
                }

View on GitHub (pinned to 322425c43b)

Solutions

1. Install httpx: `pip install httpx` (or add it to your deployment dependencies)
2. Prefer the bundled extra if provided: `pip install 'headroom[cloud]'` or equivalent
3. Verify before traffic: `python -c "import httpx"` in the same environment that runs LiteLLM

Example fix

# before
from headroom.integrations.litellm_callback import HeadroomCallback
cb = HeadroomCallback(cloud_api_key='...')  # fails at first completion without httpx

# after
# pip install httpx
from headroom.integrations.litellm_callback import HeadroomCallback
cb = HeadroomCallback(cloud_api_key='...')

import importlib.util
assert importlib.util.find_spec('httpx'), 'pip install httpx before enabling Headroom Cloud mode'

try:
    result = await litellm.acompletion(...)
except ImportError as e:
    if 'httpx' in str(e):
        logger.error('Cloud compression disabled — missing httpx; continuing uncompressed')
        raise

When it happens

Trigger: Creating the LiteLLM callback with cloud mode enabled (api_key/api_url set so _cloud_compress is used) and then sending a completion request through LiteLLM in an environment without httpx installed; _client is None on first call, triggering the lazy import path.

Common situations: Using `headroom[litellm]` or plain headroom without the cloud extra; deployments that enabled Headroom Cloud (X-Headroom-Key auth) but whose image lacks httpx; assuming the callback's import-time success means all deps are present — httpx is deferred so it slips through import checks.

Related errors

• httpx is required for Headroom Cloud mode: pip install httpx
• litellm is required for LiteLLMBackend. Install with: pip in
• No optimizer registered for '{key}'. Available: {available}
• Error: litellm required for --answer-model. Run: pip install
• anthropic package required. Install with: pip install anthro

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