{"record":{"id":"d4079f75185b4261","repo":"rohitg00/ai-engineering-from-scratch","slug":"peer-name-malformed-legacy-initialize-result","errorCode":null,"errorMessage":"{peer.name}: malformed legacy initialize result","messagePattern":"(.+?): malformed legacy initialize result","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py","lineNumber":391,"sourceCode":"            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\n        peer.server_info = server_info\n        peer.available = True\n        self._send(\n            peer,\n            {\"jsonrpc\": \"2.0\", \"method\": \"notifications/initialized\", \"params\": {}}\n        )\n\n    def _connect_peer(self, peer: Peer) -> None:\n        if peer.available and peer.era in {\"modern\", \"legacy\"}:\n            return\n        request_id = self._new_id()\n        probe = modern_request(\n            request_id,\n            \"server/discover\",\n            {},","sourceCodeStart":373,"sourceCodeEnd":409,"githubUrl":"https://github.com/rohitg00/ai-engineering-from-scratch/blob/39ea8a1c6d0b61f071226eff7ede4d4105fed820/phases/13-tools-and-protocols/08-building-an-mcp-client/code/main.py#L373-L409","documentation":"The legacy initialize result passed the version check but its capabilities field is not a dict, or serverInfo is missing/not a dict with non-empty string name and version. The client validates the full legacy result shape before activating the peer and treats a malformed payload as a hard failure.","triggerScenarios":"version is in supported_legacy but capabilities is not a dict, or serverInfo fails the isinstance/name/version string checks encoded in valid_server_info.","commonSituations":"Hand-rolled legacy server returning partial initialize results; serverInfo with numeric version or empty name; capabilities serialized as a list or null by a buggy serializer.","solutions":["Log the raw legacy initialize result and inspect capabilities/serverInfo","Fix the server to return capabilities as an object and serverInfo with non-empty string name and version","If the server is third-party, disable legacy for that peer and require modern discovery"],"exampleFix":"// before (server)\nresult = {\"protocolVersion\": \"2024-11-05\", \"serverInfo\": {\"name\": \"srv\", \"version\": 1}}\n\n// after\nresult = {\"protocolVersion\": \"2024-11-05\", \"capabilities\": {}, \"serverInfo\": {\"name\": \"srv\", \"version\": \"1.0.0\"}}","handlingStrategy":"validation","validationCode":"result = dry_run_legacy_initialize(peer)\nok = (isinstance(result.get('capabilities'), dict)\n      and isinstance(result.get('serverInfo'), dict)\n      and isinstance(result['serverInfo'].get('name'), str)\n      and isinstance(result['serverInfo'].get('version'), str))\nif not ok:\n    fix_server_initialize_result(peer)","typeGuard":"def valid_legacy_result(result) -> bool:\n    return (isinstance(result, dict)\n            and isinstance(result.get('capabilities'), dict)\n            and isinstance(result.get('serverInfo'), dict)\n            and isinstance(result['serverInfo'].get('name'), str)\n            and result['serverInfo'].get('name')\n            and isinstance(result['serverInfo'].get('version'), str)\n            and result['serverInfo'].get('version'))","tryCatchPattern":"null","preventionTips":["Contract-test the server's initialize result shape","Never hand-roll initialize responses without all required fields"],"tags":["mcp","schema-validation","legacy","handshake"],"backgroundTag":"schema-validation-failed","analyzedSha":"39ea8a1c6d0b61f071226eff7ede4d4105fed820","analyzedAt":"2026-08-26T03:13:46.626Z","schemaVersion":2},"datasetVersion":"2026-08-26T07:17:17.940Z"}