{"record":{"id":"2895a658d3c94cd0","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-2895a6","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}, but server does not report a protocol version. Please update your server to ensure compatibility.","messagePattern":"SDK protocol version mismatch: SDK supports versions (.+?)-(.+?), but server does not report a protocol version\\. Please update your server to ensure compatibility\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"critical","filePath":"python/copilot/client.py","lineNumber":4141,"sourceCode":"            client_info = _client_info_to_wire(self._options.client_info)\n            if client_info is not None:\n                connect_params[\"clientInfo\"] = client_info\n            connect_result = _ConnectResult.from_dict(\n                await self._client.request(\"connect\", connect_params)\n            )\n            server_version = connect_result.protocol_version\n        except JsonRpcError as err:\n            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,","sourceCodeStart":4123,"sourceCodeEnd":4159,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/python/copilot/client.py#L4123-L4159","documentation":"During the connect/ping handshake the SDK asks the server for its protocol version. If the server responds without reporting any version, the SDK cannot verify compatibility and raises this RuntimeError telling you to update the server.","triggerScenarios":"Connecting to a Copilot CLI server build that predates protocol version reporting (no 'connect' support and ping returns no protocolVersion), so server_version stays None after the handshake.","commonSituations":"Running an old CLI binary installed system-wide; a --no-auto-update pinned CLI; using a non-Copilot or stub server implementation on the other end of the transport.","solutions":["Update the Copilot CLI server binary to a version that reports a protocol version","Remove version pins/auto-update blockers so a current CLI is used","Verify the spawned server is the genuine Copilot CLI, not a stub or wrapper","Check that the SDK's ping fallback isn't hitting a server that omits protocolVersion"],"exampleFix":"// before\n# pinned old CLI\nconn = ConnectionOptions(cli_path=\"/usr/local/bin/copilot-cli-1.0\")\n// after\nconn = ConnectionOptions()  # resolve current CLI; let SDK manage versioning","handlingStrategy":"fallback","validationCode":"# before connecting, check CLI version on disk\nimport subprocess\nver = subprocess.run([cli_path, \"--version\"], capture_output=True, text=True).stdout\nprint(ver)  # ensure the CLI is a current build","typeGuard":null,"tryCatchPattern":"try:\n    await client.start()\nexcept RuntimeError as e:\n    if \"does not report a protocol version\" in str(e):\n        raise SystemExit(\"Copilot CLI too old; update the server binary and retry\")\n    raise","preventionTips":["Keep the Copilot CLI auto-updated or pin it to a version supporting 'connect'","Never point the SDK at stub or third-party servers","Check CLI --version during environment setup/CI"],"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"}