github/copilot-sdk · critical · RuntimeException

SDK protocol version mismatch: SDK supports versions

Error message

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.

What it means

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.

Solutions

  1. Update the server/CLI to a version that reports a protocol version
  2. Verify you are connecting to the intended server (not an old deployment)
  3. Check for proxies/middleware that strip the version field from handshake responses
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: query the server version endpoint/handshake and confirm it reports a protocol version before start()

Try / catch

try { client.start().join(); } catch (RuntimeException e) { if (e.getMessage().startsWith("SDK protocol version mismatch")) { /* update server */ } else throw e; }

Prevention

When it happens

Trigger: 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.

Common situations: Pointing the SDK at a custom or outdated server; a proxy stripping the version field; server built before protocol version reporting was added.

Related errors

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/897e70d7f9acc1f5. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/CopilotClient.java:682

            Throwable cause = e;
            while (cause instanceof java.util.concurrent.ExecutionException || cause instanceof CompletionException) {
                cause = cause.getCause();
            }
            if (cause instanceof JsonRpcException rpcEx && isUnsupportedConnectMethod(rpcEx)) {
                // Legacy server without 'connect'; fall back to 'ping'.
                // A token, if any, is silently dropped — the legacy server can't enforce one.
                var params = new HashMap<String, Object>();
                params.put("message", null);
                PingResponse pingResponse = connection.rpc.invoke("ping", params, PingResponse.class).get(30,
                        TimeUnit.SECONDS);
                serverVersion = pingResponse.protocolVersion();
            } else {
                throw e;
            }
        }

        if (serverVersion == null) {
            throw new RuntimeException("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.");
        }

        if (serverVersion < MIN_PROTOCOL_VERSION || serverVersion > expectedVersion) {
            throw new RuntimeException("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.");
        }
    }

    private static boolean isUnsupportedConnectMethod(JsonRpcException ex) {
        return ex.getCode() == METHOD_NOT_FOUND_ERROR_CODE || "Unhandled method connect".equals(ex.getMessage());
    }

    /**
     * Disconnects from the Copilot server and closes all active sessions.
     * <p>

View on GitHub (pinned to cd8cf15dc3)