BerriAI/litellm · error · HTTPException

MCP tool call timed out after {_timeout}s

Error message

MCP tool call timed out after {_timeout}s

What it means

The MCP tool call task did not finish within the configured timeout, so the awaiting side raises this HTTPException instead of blocking indefinitely. The upstream call is abandoned; no partial result is returned.

Source

Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:5074

                                type(e).__name__,
                            )
                            return client.error_tool_result(e)
                        _, www_authenticate = auth_info
                        raise MCPUpstreamAuthError(
                            status_code=401,
                            www_authenticate=www_authenticate,
                            server_name=server_label,
                        ) from e

            tool_call_coro = _call_tool_via_client(client, call_tool_params)

        tasks.append(asyncio.create_task(tool_call_coro))

        _timeout: Final = mcp_server.timeout if mcp_server.timeout is not None else MCP_CLIENT_TIMEOUT
        try:
            mcp_responses: Final = await asyncio.wait_for(asyncio.gather(*tasks), timeout=_timeout)
        except asyncio.TimeoutError:
            raise HTTPException(
                status_code=504,
                detail={
                    "error": "timeout",
                    "message": f"MCP tool call timed out after {_timeout}s",
                },
            )
        except (
            BlockedPiiEntityError,
            GuardrailRaisedException,
            HTTPException,
        ) as e:
            verbose_logger.error("Guardrail blocked MCP tool call during result check: %s", e)
            raise e

        # If proxy_logging_obj is None, the tool call result is at index 0
        # If proxy_logging_obj is not None, the tool call result is at index 1 (after the during hook task)
        result_index: Final = 1 if proxy_logging_obj else 0
        result: Final = mcp_responses[result_index]

View on GitHub (pinned to 77b7c6c40c)

Solutions

1. Increase the MCP tool timeout, or investigate why the tool is slow.

Example fix

Raise timeout in config; check upstream tool latency.

When it happens

Trigger: Thrown at litellm/proxy/_experimental/mcp_server/mcp_server_manager.py:5074 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

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