{"record":{"id":"0699d055470957fb","repo":"PrefectHQ/fastmcp","slug":"408","errorCode":"408","errorMessage":"Timed out while waiting for response.","messagePattern":"Timed out while waiting for response\\.","errorType":"error_code","errorClass":"MCPError","httpStatus":408,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/exceptions.py","lineNumber":59,"sourceCode":"def is_request_error(exc: BaseException) -> bool:\n    \"\"\"Return whether an exception is an httpx2 or legacy-httpx request error.\"\"\"\n    return isinstance(exc, httpx2.RequestError) or _is_legacy_httpx_exception(\n        exc, \"RequestError\"\n    )\n\n\ndef iter_exc(group: BaseExceptionGroup):\n    for exc in group.exceptions:\n        if isinstance(exc, BaseExceptionGroup):\n            yield from iter_exc(exc)\n        else:\n            yield exc\n\n\ndef _exception_handler(group: BaseExceptionGroup):\n    for leaf in iter_exc(group):\n        if isinstance(leaf, httpx2.ConnectTimeout):\n            raise MCPError(\n                code=httpx2.codes.REQUEST_TIMEOUT,\n                message=\"Timed out while waiting for response.\",\n            )\n        raise leaf\n\n\n# this catch handler is used to catch taskgroup exception groups and raise the\n# first exception. This allows more sane debugging.\n_catch_handlers: Mapping[\n    type[BaseException] | Iterable[type[BaseException]],\n    Callable[[BaseExceptionGroup[Any]], Any],\n] = {\n    Exception: _exception_handler,\n}\n\n\ndef get_catch_handlers() -> Mapping[\n    type[BaseException] | Iterable[type[BaseException]],","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/exceptions.py#L41-L77","documentation":"When batching requests over an HTTP transport, a leaf `httpx.ConnectTimeout` inside an exception group is converted into an MCPError with code 408 (Request Timeout). This normalizes low-level HTTP connect timeouts into a single recognizable MCP error so callers can detect 'server unreachable / too slow' uniformly.","triggerScenarios":"Client connecting to an MCP server whose host does not respond within httpx's connect timeout — e.g. `Client('https://slow-host/mcp')` during a request that surfaces the exception group through `_exception_handler`.","commonSituations":"Wrong host/port, server not started, network latency/firewall dropping SYN packets, DNS resolving but host down, container not listening.","solutions":["Verify the server is running and the URL/host/port are correct.","Increase the client timeout (e.g. `httpx.Timeout(connect=30)`) passed to the Client.","Check network/firewall/VPN and DNS resolution for the host.","Retry with backoff if the server is known to be intermittently slow."],"exampleFix":"// before\nasync with Client('https://api.example.com/mcp') as client: ...\n// after\nimport httpx\ntimeout = httpx.Timeout(60.0, connect=30.0)\nasync with Client('https://api.example.com/mcp', timeout=timeout) as client: ...","handlingStrategy":"retry","validationCode":"import socket\nsocket.create_connection((host, port), timeout=5)  # probe before connecting","typeGuard":"def is_timeout(err: BaseException) -> bool:\n    from fastmcp_exceptions import MCPError  # or check code attribute\n    return getattr(err, 'code', None) == 408 or isinstance(getattr(err, 'original', None), Exception)","tryCatchPattern":"for attempt in range(3):\n    try:\n        async with Client(url, timeout=httpx.Timeout(60, connect=30)) as c:\n            return await c.list_tools()\n    except MCPError as e:\n        if e.code != 408:\n            raise\n        await asyncio.sleep(2 ** attempt)\nraise ConnectionError(f'server unreachable: {url}')","preventionTips":["Set explicit httpx connect timeouts on clients","Health-check the MCP server URL before starting workflows","Confirm server process/port is up in CI before integration tests"],"tags":["network","timeout","httpx","client"],"backgroundTag":"connection-timeout","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}