{"record":{"id":"6b09ca4b790735eb","repo":"rohitg00/ai-engineering-from-scratch","slug":"peer-name-legacy-initialize-returned-an-error","errorCode":null,"errorMessage":"{peer.name}: legacy initialize returned an error","messagePattern":"(.+?): legacy initialize returned an error","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py","lineNumber":376,"sourceCode":"        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\")\n        if not isinstance(capabilities, dict) or not valid_server_info:\n            raise RuntimeError(f\"{peer.name}: malformed legacy initialize result\")\n        peer.era = \"legacy\"\n        peer.protocol_version = version\n        peer.capabilities = capabilities","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py#L358-L394","documentation":"The legacy server answered the initialize probe with a JSON-RPC error response instead of a result. decode_rpc_response matched the request id but classified the message as an error, so the legacy handshake is abandoned with the peer's name attached.","triggerScenarios":"_probe_legacy receives a valid dict response, decode_rpc_response(response, request_id) returns kind='error', i.e. the payload contains an error object for the initialize request.","commonSituations":"Legacy server rejecting the clientInfo or protocol parameters; server requiring auth before initialize; method name mismatch between client and an old server build.","solutions":["Inspect response['error'] to see the server's rejection reason","Verify the legacy_request payload (clientInfo, protocolVersion) matches what the server expects","Check whether the server requires an auth/notification step before initialize","Update or restart the legacy server if its error is spurious"],"exampleFix":"// before\ntry:\n    client.connect_all()\nexcept RuntimeError as e:\n    pass  # error swallowed, cause unknown\n\n// after\ntry:\n    client.connect_all()\nexcept RuntimeError as e:\n    log.error(\"connect failed: %s\", e)  # message includes the RPC error payload","handlingStrategy":"try-catch","validationCode":"null","typeGuard":"null","tryCatchPattern":"try:\n    client.connect_all()\nexcept RuntimeError as e:\n    if \"legacy initialize returned an error\" in str(e):\n        inspect_server_error_log(peer.name)","preventionTips":["Log full RPC error payloads during integration bring-up","Verify clientInfo/protocol params the legacy server expects"],"tags":["mcp","rpc-error","legacy","handshake"],"backgroundTag":"json-rpc-error-response","analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","schemaVersion":2},"datasetVersion":"2026-08-26T07:17:17.940Z"}