{"record":{"id":"a7e120c69296a41e","repo":"BerriAI/litellm","slug":"upstream-mcp-server-server-name-r-returned-stat","errorCode":null,"errorMessage":"Upstream MCP server {server_name!r} returned {status_code}","messagePattern":"Upstream MCP server (.+?) returned (.+?)","errorType":"exception","errorClass":"MCPUpstreamAuthError","httpStatus":null,"severity":"error","filePath":"litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py","lineNumber":109,"sourceCode":"            return response.status_code, response.headers.get(\"www-authenticate\")\n    return None\n\n\ndef raise_classified_list_failure(\n    exc: BaseException,\n    server_name: str,\n    suppress_challenge: bool = False,\n) -> NoReturn:\n    \"\"\"The one place a failed server fetch chooses its carrier: an upstream 401/403 travels as\n    ``MCPUpstreamAuthError`` with the upstream's own challenge preserved (a challenge is only ever\n    fabricated at the HTTP edge, and only for a 401), everything else as ``MCPServerListError`` with\n    a classified fault. Every fetch site delegates here so the two channels cannot drift apart per\n    call site. ``suppress_challenge`` is for dcr_bridge servers, whose upstream challenge points\n    clients at the wrong protected-resource metadata and must never relay.\"\"\"\n    auth: Final = upstream_auth_challenge(exc)\n    if auth is not None:\n        status_code, challenge = auth\n        raise MCPUpstreamAuthError(\n            status_code=status_code,\n            www_authenticate=None if suppress_challenge else challenge,\n            server_name=server_name,\n        ) from exc\n    raise MCPServerListError(classify_list_exception(exc), server_name) from exc\n\n\ndef classify_list_exception(exc: BaseException) -> ServerListFault:\n    \"\"\"Classify a per-server listing failure into exactly one outcome. Total: an exception this\n    function cannot recognize is the gateway's own fault (``internal``), never a re-raise.\"\"\"\n    if isinstance(exc, MCPServerListError) and isinstance(exc.fault, ServerListFault):\n        return exc.fault\n    if isinstance(exc, MCPUpstreamAuthError):\n        tag: Final = \"forbidden\" if exc.status_code == 403 else \"auth_required\"\n        return ServerListFault(tag=tag, status_code=exc.status_code)\n    if isinstance(exc, TimeoutError):\n        return ServerListFault(tag=\"timeout\")\n    if isinstance(exc, ConnectionError):","sourceCodeStart":91,"sourceCodeEnd":127,"githubUrl":"https://github.com/BerriAI/litellm/blob/77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8/litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py#L91-L127","documentation":"The unified exit point for failed MCP server tool fetches: any non-auth upstream failure (classified status code included) is re-raised as MCPServerListError carrying this message. Route-level policy then relays it (single-server) or absorbs it (aggregator).","triggerScenarios":"Thrown at litellm/proxy/_experimental/mcp_server/faults/list_outcomes.py:109 when the library encounters an invalid state.","commonSituations":"See trigger scenarios.","solutions":["Inspect the upstream server's response status and body for the cause.","Check upstream server health and authentication."],"exampleFix":"Check proxy logs for the upstream error detail.","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":null,"preventionTips":[],"tags":[],"backgroundTag":null,"analyzedSha":"77b7c6c40c0c5aa5fbcb1d6a1825ac39ca8829b8","analyzedAt":"2026-08-18T11:44:31.656Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}