{"record":{"id":"e123090fc45e0758","repo":"rohitg00/ai-engineering-from-scratch","slug":"peer-name-bounded-legacy-probe-failed-closed","errorCode":null,"errorMessage":"{peer.name}: bounded legacy probe failed closed","messagePattern":"(.+?): bounded legacy probe failed closed","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py","lineNumber":371,"sourceCode":"    def _probe_legacy(self, peer: Peer, trigger: str) -> None:\n        if not peer.allow_legacy:\n            raise RuntimeError(\n                f\"{peer.name}: {trigger}; legacy compatibility is not allowlisted\"\n            )\n        request_id = self._new_id()\n        initialize = legacy_request(\n            request_id,\n            \"initialize\",\n            {\n                \"protocolVersion\": self.supported_legacy[0],\n                \"capabilities\": self.client_capabilities.copy(),\n                \"clientInfo\": CLIENT_INFO.copy(),\n            },\n        )\n        try:\n            response = self._send(peer, initialize, self.legacy_probe_timeout_ms)\n        except (TimeoutError, ConnectionError) as exc:\n            raise RuntimeError(f\"{peer.name}: bounded legacy probe failed closed\") from exc\n        if not isinstance(response, dict):\n            raise RuntimeError(f\"{peer.name}: bounded legacy probe returned no result\")\n        kind, payload = decode_rpc_response(response, request_id)\n        if kind != \"result\":\n            raise RuntimeError(f\"{peer.name}: legacy initialize returned an error\")\n        result = payload\n        version = result.get(\"protocolVersion\")\n        capabilities = result.get(\"capabilities\")\n        server_info = result.get(\"serverInfo\")\n        valid_server_info = (\n            isinstance(server_info, dict)\n            and isinstance(server_info.get(\"name\"), str)\n            and bool(server_info[\"name\"])\n            and isinstance(server_info.get(\"version\"), str)\n            and bool(server_info[\"version\"])\n        )\n        if version not in self.supported_legacy:\n            raise RuntimeError(f\"{peer.name}: unsupported legacy protocol revision\")","sourceCodeStart":353,"sourceCodeEnd":389,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py#L353-L389","documentation":"The legacy initialize probe was sent with a bounded timeout (legacy_probe_timeout_ms) and the transport raised TimeoutError or ConnectionError. The client deliberately fails closed rather than retrying indefinitely, wrapping the transport error to identify which peer and which stage failed.","triggerScenarios":"peer.allow_legacy is True, _probe_legacy sends legacy_request('initialize') via self._send(peer, ..., self.legacy_probe_timeout_ms), and the send times out or the connection drops before a response arrives.","commonSituations":"Legacy server that is slow to answer initialize; dead peer process behind a still-open socket; firewall dropping responses; legacy_probe_timeout_ms configured too low for a cold-starting server.","solutions":["Raise legacy_probe_timeout_ms on the client to cover the server's startup latency","Verify the peer process is alive and listening before connect_all","Check network path/firewall between client and peer","Confirm the server actually speaks the legacy initialize method at all"],"exampleFix":"// before\nclient = McpClient(..., legacy_probe_timeout_ms=500)\n\n// after\nclient = McpClient(..., legacy_probe_timeout_ms=5000)","handlingStrategy":"retry","validationCode":"if not peer_reachable(peer):\n    raise SystemExit(f\"{peer.name} unreachable before connect\")","typeGuard":"null","tryCatchPattern":"try:\n    client.connect_all()\nexcept RuntimeError as e:\n    if \"legacy probe failed closed\" in str(e) and transient_network():\n        client.connect_all()  # one bounded retry after fixing the network","preventionTips":["Size legacy_probe_timeout_ms to the slowest observed server startup","Health-check peers before connect_all"],"tags":["mcp","timeout","network","legacy"],"backgroundTag":"connection-timeout","analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","schemaVersion":2},"datasetVersion":"2026-08-26T07:17:17.940Z"}