headroomlabs-ai/headroom · error · ValueError

model_limit is required. Provide it via kwargs or configure

Error message

model_limit is required. Provide it via kwargs or configure model_context_limits in HeadroomClient.

What it means

Raised by the pipeline's transform entry point when `model_limit` is not present in kwargs. The pipeline needs the model's context window size to make budget decisions, and it deliberately does not guess: no limit means no safe compression math. Normal callers (HeadroomClient) inject it from the `model_context_limits` config; calling the pipeline directly without it is the error.

Source

Thrown at headroom/transforms/pipeline.py:267

                - request_id: Optional request ID for diff artifact.
                - waste_messages: Optional richer conversion of the same request
                  used for waste-signal detection only (never transformed).

        Returns:
            Combined TransformResult.
        """
        record_metrics = kwargs.pop("record_metrics", True)
        waste_messages = kwargs.pop("waste_messages", None)
        waste_signal_token_limit = int(
            kwargs.pop("waste_signal_token_limit", MAX_WASTE_SIGNAL_DETECTION_TOKENS)
        )
        tokenizer = self._get_tokenizer(model)
        provider_name = self._provider_name()

        # Get model limit from kwargs (should be set by client)
        model_limit = kwargs.get("model_limit")
        if model_limit is None:
            raise ValueError(
                "model_limit is required. Provide it via kwargs or "
                "configure model_context_limits in HeadroomClient."
            )

        # Start with original tokens
        # Circuit breaker open — pass through untouched (issue #847).
        if self._breaker_is_open():
            passthrough_tokens = tokenizer.count_messages(messages)
            return TransformResult(
                messages=messages,
                tokens_before=passthrough_tokens,
                tokens_after=passthrough_tokens,
                transforms_applied=["pipeline:circuit_open"],
            )

        t_count = time.perf_counter()
        tokens_before = tokenizer.count_messages(messages)
        count_ms = (time.perf_counter() - t_count) * 1000

View on GitHub (pinned to 322425c43b)

Solutions

1. Pass the limit explicitly: `pipeline.transform(messages, model=..., model_limit=200000)`
2. Configure the limit once in the client: `HeadroomClient(model_context_limits={"my-model": 200000})` so every call is injected automatically
3. If calling from custom code, mirror what HeadroomClient does — resolve the limit from your config and forward it in kwargs

Example fix

# before
result = pipeline.transform(messages, model="my-model")

# after
client = HeadroomClient(model_context_limits={"my-model": 128000})
result = client.pipeline.transform(messages, model="my-model")  # model_limit injected
# or directly:
result = pipeline.transform(messages, model="my-model", model_limit=128000)

MODEL_LIMITS = {"gpt-4o": 128000, "claude-3-5": 200000}

def limit_for(model: str) -> int:
    limit = MODEL_LIMITS.get(model)
    if limit is None:
        raise ValueError(f"no context limit configured for {model!r}; add it to MODEL_LIMITS")
    return limit

result = pipeline.transform(messages, model=model, model_limit=limit_for(model))

def has_model_limit(kwargs: dict) -> bool:
    return isinstance(kwargs.get("model_limit"), int) and kwargs["model_limit"] > 0

try:
    result = pipeline.transform(messages, model=model)
except ValueError as e:
    if "model_limit is required" in str(e):
        result = pipeline.transform(messages, model=model, model_limit=MODEL_LIMITS[model])
    else:
        raise

When it happens

Trigger: Calling `pipeline.transform(messages, model=...)` (or `run`/equivalent) directly without `model_limit=...` in kwargs, while the wrapping HeadroomClient has no entry for that model in `model_context_limits`.

Common situations: Using a new/unlisted model name (e.g. a freshly released or self-hosted model) with no `model_context_limits` entry; bypassing HeadroomClient in scripts or tests and calling the pipeline directly; a client upgrade that changed how limits are resolved.

Related errors

• token_url is required
• recommendations IO error at {path}: {source}
• bedrock_eventstream_parse_failed
• bedrock_eventstream_crc_mismatch
• Error: {e}

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