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 reports version ${serverVersion}. Please update your SDK or server to ensure compatibility.

What it means

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.

Solutions

  1. Upgrade the SDK to a version supporting the server's protocol version, or downgrade the server
  2. Pin matching SDK and CLI versions in your build/deployment
  3. Verify which CLI binary is actually being spawned (which/path)
Defensive patterns

Strategy: try-catch

Validate before calling

// preflight: fetch server protocol version and compare with the SDK's supported MIN_PROTOCOL_VERSION..expectedVersion range before start()

Try / catch

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

Prevention

When it happens

Trigger: Connecting to a server older than MIN_PROTOCOL_VERSION or newer than the SDK's expectedVersion during startCoreBody.

Common situations: 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.

Related errors

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

Appendix: source

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

                // 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>
     * This method performs graceful cleanup:
     * <ol>
     * <li>Closes all active sessions (releases in-memory resources)</li>
     * <li>Requests runtime shutdown for SDK-owned CLI processes</li>
     * <li>Closes the JSON-RPC connection</li>
     * <li>Terminates the CLI server process (if spawned by this client)</li>

View on GitHub (pinned to cd8cf15dc3)