{"record":{"id":"287224df5886f91f","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-287224","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${expectedVersion}, but server reports version ${serverVersion}. 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":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":688,"sourceCode":"                // A token, if any, is silently dropped — the legacy server can't enforce one.\n                var params = new HashMap<String, Object>();\n                params.put(\"message\", null);\n                PingResponse pingResponse = connection.rpc.invoke(\"ping\", params, PingResponse.class).get(30,\n                        TimeUnit.SECONDS);\n                serverVersion = pingResponse.protocolVersion();\n            } else {\n                throw e;\n            }\n        }\n\n        if (serverVersion == null) {\n            throw new RuntimeException(\"SDK protocol version mismatch: SDK supports versions \" + MIN_PROTOCOL_VERSION\n                    + \"-\" + expectedVersion + \", but server does not report a protocol version. \"\n                    + \"Please update your server to ensure compatibility.\");\n        }\n\n        if (serverVersion < MIN_PROTOCOL_VERSION || serverVersion > expectedVersion) {\n            throw new RuntimeException(\"SDK protocol version mismatch: SDK supports versions \" + MIN_PROTOCOL_VERSION\n                    + \"-\" + expectedVersion + \", but server reports version \" + serverVersion + \". \"\n                    + \"Please update your SDK or server to ensure compatibility.\");\n        }\n    }\n\n    private static boolean isUnsupportedConnectMethod(JsonRpcException ex) {\n        return ex.getCode() == METHOD_NOT_FOUND_ERROR_CODE || \"Unhandled method connect\".equals(ex.getMessage());\n    }\n\n    /**\n     * Disconnects from the Copilot server and closes all active sessions.\n     * <p>\n     * This method performs graceful cleanup:\n     * <ol>\n     * <li>Closes all active sessions (releases in-memory resources)</li>\n     * <li>Requests runtime shutdown for SDK-owned CLI processes</li>\n     * <li>Closes the JSON-RPC connection</li>\n     * <li>Terminates the CLI server process (if spawned by this client)</li>","sourceCodeStart":670,"sourceCodeEnd":706,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L670-L706","documentation":"The SDK supports protocol versions MIN_PROTOCOL_VERSION through expectedVersion. If the server reports a version outside that range, verifyProtocolVersion throws RuntimeException naming both the SDK's supported range and the server's reported version — the version contract protects against incompatible RPC calls.","triggerScenarios":"Connecting to a server older than MIN_PROTOCOL_VERSION or newer than the SDK's expectedVersion during startCoreBody.","commonSituations":"Pinning an old CLI while upgrading the SDK, or vice versa; environment (e.g. PATH) resolving a different CLI version than expected; mixing SDK and server releases.","solutions":["Upgrade the SDK to a version supporting the server's protocol version, or downgrade the server","Pin matching SDK and CLI versions in your build/deployment","Verify which CLI binary is actually being spawned (which/path)"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// preflight: fetch server protocol version and compare with the SDK's supported MIN_PROTOCOL_VERSION..expectedVersion range before start()","typeGuard":null,"tryCatchPattern":"try { client.start().join(); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"SDK protocol version mismatch\")) { /* align SDK and server versions */ } else throw e; }","preventionTips":["Upgrade/downgrade so server version falls within the SDK's reported range","Pin SDK and CLI versions together in builds and CI","Log the server-reported version at startup"],"tags":["java","protocol-version","version-mismatch","compatibility"],"backgroundTag":"protocol-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"}