BerriAI/litellm · error · HTTPException

Agent '{agent.agent_id}' requires x-litellm-trace-id header

Error message

Agent '{agent.agent_id}' requires x-litellm-trace-id header on all inbound requests.

What it means

Enforced when the agent's litellm_params set require_trace_id_on_calls_to_agent: every inbound call must carry x-litellm-trace-id so the proxy can correlate traffic; missing header is rejected 400 before dispatch.

Source

Thrown at litellm/proxy/agent_endpoints/a2a_endpoints.py:176

    agent = global_agent_registry.get_agent_by_id(agent_id=agent_id)
    if agent is None:
        agent = global_agent_registry.get_agent_by_name(agent_name=agent_id)
    return agent


def _enforce_inbound_trace_id(agent: "AgentResponse", request: Request) -> None:
    """Raise 400 if agent requires x-litellm-trace-id on inbound calls and it is missing."""
    agent_litellm_params: Final = agent.litellm_params or {}
    if not agent_litellm_params.get("require_trace_id_on_calls_to_agent"):
        return

    from litellm.proxy.litellm_pre_call_utils import get_chain_id_from_headers

    headers_dict: Final = dict(request.headers)
    trace_id: Final = get_chain_id_from_headers(headers_dict)
    if not trace_id:
        raise HTTPException(
            status_code=400,
            detail=(f"Agent '{agent.agent_id}' requires x-litellm-trace-id header on all inbound requests."),
        )


async def _forward_jsonrpc(
    agent_url: str,
    body: dict[str, object],
    extra_headers: Mapping[str, str] | None = None,
) -> dict[str, Any]:
    from litellm.llms.custom_httpx.http_handler import get_async_httpx_client
    from litellm.types.llms.custom_http import httpxSpecialProvider

    headers: Final = {"Content-Type": "application/json", **(extra_headers or {})}
    handler: Final = get_async_httpx_client(
        llm_provider=httpxSpecialProvider.A2A,
        params={"timeout": 60.0},
    )

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Include the x-litellm-trace-id header on requests to this agent.

Example fix

headers['x-litellm-trace-id']=str(uuid4())

When it happens

Trigger: Thrown at litellm/proxy/agent_endpoints/a2a_endpoints.py:176 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/064bc12ac7929736. Report an issue: GitHub.