BerriAI/litellm · error · ValueError

headers is required

Error message

headers is required

What it means

validate_input_kwargs raises when 'headers' is missing from kwargs or is not a dict. The bridge forwards request headers (auth, org id, extra headers) to the Responses API call. In the standard pipeline headers are always initialized as a dict before the handler runs, so this fires only on direct/manual invocations.

Source

Thrown at litellm/completion_extras/litellm_responses_transformation/handler.py:130

        custom_llm_provider: Final = typed_kwargs.get("custom_llm_provider")
        if custom_llm_provider is None or not isinstance(custom_llm_provider, str):
            raise ValueError("custom_llm_provider is required")

        messages: Final = typed_kwargs.get("messages")
        if messages is None or not isinstance(messages, list):
            raise ValueError("messages is required")

        optional_params: Final = typed_kwargs.get("optional_params")
        if optional_params is None or not isinstance(optional_params, dict):
            raise ValueError("optional_params is required")

        litellm_params: Final = typed_kwargs.get("litellm_params")
        if litellm_params is None or not isinstance(litellm_params, dict):
            raise ValueError("litellm_params is required")

        headers: Final = typed_kwargs.get("headers")
        if headers is None or not isinstance(headers, dict):
            raise ValueError("headers is required")

        model_response: Final = typed_kwargs.get("model_response")
        if model_response is None or not isinstance(model_response, ModelResponse):
            raise ValueError("model_response is required")

        logging_obj: Final = typed_kwargs.get("logging_obj")
        if logging_obj is None or not isinstance(logging_obj, LiteLLMLoggingObj):
            raise ValueError("logging_obj is required")

        return ResponsesToCompletionBridgeHandlerInputKwargs(
            model=model,
            messages=messages,
            optional_params=optional_params,
            litellm_params=litellm_params,
            headers=headers,
            model_response=model_response,
            logging_obj=logging_obj,
            custom_llm_provider=custom_llm_provider,

View on GitHub (pinned to 6c2dcb801b)

Solutions

1. Call litellm.completion so headers default to {} internally
2. If direct, include headers={}
3. Ensure extra_headers config is merged into the dict, not passed separately

Example fix

# before
kwargs = {"model": m, "messages": msgs, "litellm_params": {}}

# after
kwargs = {"model": m, "messages": msgs, "litellm_params": {}, "headers": {}}

def has_headers_kwarg(kwargs: dict) -> bool:
    return isinstance(kwargs.get("headers"), dict)

def is_dict_param(v) -> bool:
    return isinstance(v, dict)

When it happens

Trigger: Direct bridge handler call with a kwargs dict lacking the headers key; headers passed as None.

Common situations: Hand-built kwargs in custom routers or proxies; older code written against a handler version that defaulted headers instead of requiring them.

Related errors

• model is required
• custom_llm_provider is required
• messages is required
• optional_params is required
• litellm_params is required

AI-assisted analysis of BerriAI/litellm@6c2dcb801b (2026-08-15). Data as JSON: /api/errors/1bd51652d8b5b55c. Report an issue: GitHub.