{"record":{"id":"0a0c5aea35251300","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-0a0c5a","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}, but server reports version {server_version}. Please update your SDK or server to ensure compatibility.","messagePattern":"SDK protocol version mismatch: SDK supports versions (.+?)-(.+?), but server reports version (.+?)\\. Please update your SDK or server to ensure compatibility\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/copilot/client.py","lineNumber":4149,"sourceCode":"            if err.code == -32601 or err.message == \"Unhandled method connect\":\n                # Legacy server without `connect`; fall back to `ping`. A token, if any,\n                # is silently dropped — the legacy server can't enforce one.\n                used_fallback_ping = True\n                ping_result = await self.ping()\n                server_version = ping_result.protocol_version\n            else:\n                raise\n\n        if server_version is None:\n            raise RuntimeError(\n                \"SDK protocol version mismatch: \"\n                f\"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}\"\n                \", but server does not report a protocol version. \"\n                \"Please update your server to ensure compatibility.\"\n            )\n\n        if server_version < _MIN_PROTOCOL_VERSION or server_version > max_version:\n            raise RuntimeError(\n                \"SDK protocol version mismatch: \"\n                f\"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}\"\n                f\", but server reports version {server_version}. \"\n                \"Please update your SDK or server to ensure compatibility.\"\n            )\n\n        self._negotiated_protocol_version = server_version\n        log_timing(\n            logger,\n            logging.DEBUG,\n            \"CopilotClient._verify_protocol_version protocol handshake complete\",\n            handshake_start,\n            protocol_version=server_version,\n            used_fallback_ping=used_fallback_ping,\n        )\n\n    def _convert_provider_to_wire_format(\n        self, provider: ProviderConfig | dict[str, Any]","sourceCodeStart":4131,"sourceCodeEnd":4167,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L4131-L4167","documentation":"After the handshake the SDK compares the server's reported protocol version against its supported range [_MIN_PROTOCOL_VERSION, max_version]. If the server version is older or newer than the SDK supports, this RuntimeError is raised advising to update the SDK or server.","triggerScenarios":"Connecting when server_version < _MIN_PROTOCOL_VERSION (very old server) or server_version > max_version (server newer than the installed SDK), as reported in the 'connect'/'ping' response.","commonSituations":"SDK pip package lagging behind an auto-updated CLI (server too new); a very old CLI paired with a current SDK (server too old); mixed-version environments where different machines install CLI and SDK independently.","solutions":["Compare the reported server version in the message to your SDK's supported range and upgrade whichever side is stale","pip install --upgrade the Copilot SDK when the server is newer","Update the Copilot CLI binary when the server is older than the SDK's minimum","Pin CLI auto-update and SDK versions together in CI to keep them in lockstep"],"exampleFix":"// before\npip install copilot==0.1.0  # old SDK vs auto-updated CLI\n// after\npip install --upgrade copilot  # or pin: copilot==X matching CLI version X","handlingStrategy":"fallback","validationCode":"# compare CLI and SDK versions before connecting\nimport subprocess\ncli_ver = subprocess.run([cli_path, \"--version\"], capture_output=True, text=True).stdout.strip()\nimport copilot\nprint(cli_ver, copilot.__version__)  # keep in lockstep","typeGuard":null,"tryCatchPattern":"try:\n    await client.start()\nexcept RuntimeError as e:\n    if \"protocol version mismatch\" in str(e):\n        # upgrade SDK and/or CLI, then retry\n        raise SystemExit(\"update SDK or CLI and retry\")\n    raise","preventionTips":["Pin SDK and CLI versions together in CI and deployment","Upgrade the pip SDK whenever the CLI auto-updates to a newer protocol","Monitor the SDK changelog for protocol range changes"],"tags":["protocol-version","version-mismatch","compatibility","handshake","python"],"backgroundTag":"version-mismatch","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}