{"record":{"id":"ce4fb2b6bc153778","repo":"can1357/oh-my-pi","slug":"rpc-protocol-v2-negotiation-failed-ce4fb2","errorCode":null,"errorMessage":"RPC protocol v2 negotiation failed","messagePattern":"RPC protocol v2 negotiation failed","errorType":"exception","errorClass":"RpcError","httpStatus":null,"severity":"error","filePath":"python/omp-rpc/src/omp_rpc/client.py","lineNumber":660,"sourceCode":"                    f\"RPC process stopped before ready: {error}. Stderr: {stderr}\"\n                ) from error\n            raise RpcTimeoutError(\n                f\"Timed out waiting for RPC ready signal. Stderr: {stderr}\"\n            )\n\n        ready_event = self._ready_event\n        if (\n            ready_event is not None\n            and ready_event.supported_protocol_versions is not None\n            and 2 in ready_event.supported_protocol_versions\n            and ready_event.max_frame_bytes == _MAX_RPC_FRAME_BYTES\n            and ready_event.max_reassembled_frame_bytes == _MAX_RPC_REASSEMBLED_BYTES\n        ):\n            try:\n                self._protocol_v2_enabled = True\n                negotiation = self._request(\"negotiate_protocol\", protocolVersion=2)\n                if negotiation.get(\"protocolVersion\") != 2:\n                    raise RpcError(\"RPC protocol v2 negotiation failed\")\n                self._protocol_version = 2\n            except BaseException:\n                self.stop()\n                raise\n\n        if self._custom_tools:\n            self.set_custom_tools(self._custom_tools)\n        if self._host_uris:\n            self.set_host_uris(self._host_uris)\n        return self\n\n    def stop(self) -> None:\n        process = self._process\n        if process is None:\n            return\n\n        self._stopping = True\n        for pending_call in self._pending_host_tool_calls.values():","sourceCodeStart":642,"sourceCodeEnd":678,"githubUrl":"https://github.com/can1357/oh-my-pi/blob/969062200754ea02cfac922e5ebb8c608c079e15/python/omp-rpc/src/omp_rpc/client.py#L642-L678","documentation":"During RpcClient.start(), after capability checks confirm both sides support protocol v2, the client sends a 'negotiate_protocol' request with protocolVersion=2. If the server's response does not echo protocolVersion == 2, the client assumes negotiation failed, raises this RpcError, and stops the client process before re-raising. This guards against servers that advertise v2 support but refuse or mis-handle the negotiation handshake.","triggerScenarios":"Calling start() on a client whose server reports v2-compatible capabilities (matching _MAX_RPC_REASSEMBLED_BYTES etc.) but whose 'negotiate_protocol' response payload lacks protocolVersion: 2 — e.g. an older or mismatched omp server binary, or a stub/test server returning an unexpected payload.","commonSituations":"Version skew between the Python client package and the installed omp server (client upgraded, server binary stale, or vice versa); custom/mock RPC servers that don't implement negotiate_protocol correctly; proxy wrappers that strip or rewrite response fields.","solutions":["Upgrade or rebuild the omp server binary so its version matches the Python omp-rpc client package","Pin the client and server to compatible versions (install both from the same release)","Log the negotiate_protocol response payload to confirm what the server actually returned","If a server genuinely cannot do v2, use a client/server pair whose capabilities do not advertise v2 so negotiation is skipped"],"exampleFix":"# before: mismatched versions\npip install -U omp-rpc   # client now expects v2, stale server binary remains\n\n# after: keep both sides in sync\npip install -U omp-rpc omp  # or rebuild/replace the server binary to the matching release","handlingStrategy":"try-catch","validationCode":"# check versions before start()\nimport omp_rpc\nprint(\"client:\", omp_rpc.__version__)  # ensure matching server binary is installed\n","typeGuard":"def negotiation_ok(payload: dict) -> bool:\n    return isinstance(payload, dict) and payload.get(\"protocolVersion\") == 2\n","tryCatchPattern":"try:\n    client.start()\nexcept RpcError as e:\n    if \"protocol v2 negotiation failed\" in str(e):\n        upgrade_server_and_restart()  # then retry start()\n    else:\n        raise\n","preventionTips":["Always install the omp server binary from the same release as the omp-rpc client package","Pin both versions in requirements/lockfiles","Smoke-test client.start() against the pinned server in CI","Log negotiate_protocol payloads when debugging startup failures"],"tags":["rpc","protocol-negotiation","version-mismatch","handshake"],"backgroundTag":"rpc-protocol-negotiation-failed","analyzedSha":"969062200754ea02cfac922e5ebb8c608c079e15","analyzedAt":"2026-08-31T10:29:35.737Z","schemaVersion":2},"datasetVersion":"2026-08-31T14:17:45.589Z"}