{"record":{"id":"897e70d7f9acc1f5","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-897e70","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions ${MIN_PROTOCOL_VERSION}-${expectedVersion}, 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":"RuntimeException","httpStatus":null,"severity":"critical","filePath":"java/sdk/src/main/java/com/github/copilot/CopilotClient.java","lineNumber":682,"sourceCode":"            Throwable cause = e;\n            while (cause instanceof java.util.concurrent.ExecutionException || cause instanceof CompletionException) {\n                cause = cause.getCause();\n            }\n            if (cause instanceof JsonRpcException rpcEx && isUnsupportedConnectMethod(rpcEx)) {\n                // Legacy server without 'connect'; fall back to 'ping'.\n                // 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>","sourceCodeStart":664,"sourceCodeEnd":700,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotClient.java#L664-L700","documentation":"After connecting, CopilotClient verifies the server's reported protocol version against the range the SDK supports (MIN_PROTOCOL_VERSION..expectedVersion). If the server reports no protocol version at all, verifyProtocolVersion throws RuntimeException stating the SDK's supported range and advising a server update, since compatibility cannot be established.","triggerScenarios":"Connecting to an external server (via CliUrl or a spawned CLI) whose handshake/version response lacks a protocol version field — typically an old or non-standard server.","commonSituations":"Pointing the SDK at a custom or outdated server; a proxy stripping the version field; server built before protocol version reporting was added.","solutions":["Update the server/CLI to a version that reports a protocol version","Verify you are connecting to the intended server (not an old deployment)","Check for proxies/middleware that strip the version field from handshake responses"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// preflight: query the server version endpoint/handshake and confirm it reports a protocol version before start()","typeGuard":null,"tryCatchPattern":"try { client.start().join(); } catch (RuntimeException e) { if (e.getMessage().startsWith(\"SDK protocol version mismatch\")) { /* update server */ } else throw e; }","preventionTips":["Keep the server/CLI updated to a version that reports a protocol version","Pin known-compatible SDK/server pairs","Watch for proxies stripping version fields"],"tags":["java","protocol-version","compatibility","server"],"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"}