github/copilot-sdk · critical · RuntimeError

SDK protocol version mismatch: SDK supports versions

Error message

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.

What it means

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.

Solutions

  1. Update the Copilot CLI server binary to a version that reports a protocol version
  2. Remove version pins/auto-update blockers so a current CLI is used
  3. Verify the spawned server is the genuine Copilot CLI, not a stub or wrapper
  4. Check that the SDK's ping fallback isn't hitting a server that omits protocolVersion

Example fix

// before
# pinned old CLI
conn = ConnectionOptions(cli_path="/usr/local/bin/copilot-cli-1.0")
// after
conn = ConnectionOptions()  # resolve current CLI; let SDK manage versioning
Defensive patterns

Strategy: fallback

Validate before calling

# before connecting, check CLI version on disk
import subprocess
ver = subprocess.run([cli_path, "--version"], capture_output=True, text=True).stdout
print(ver)  # ensure the CLI is a current build

Try / catch

try:
    await client.start()
except RuntimeError as e:
    if "does not report a protocol version" in str(e):
        raise SystemExit("Copilot CLI too old; update the server binary and retry")
    raise

Prevention

When it happens

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

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

Related errors

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

Appendix: source

Thrown at python/copilot/client.py:4141

            client_info = _client_info_to_wire(self._options.client_info)
            if client_info is not None:
                connect_params["clientInfo"] = client_info
            connect_result = _ConnectResult.from_dict(
                await self._client.request("connect", connect_params)
            )
            server_version = connect_result.protocol_version
        except JsonRpcError as err:
            if err.code == -32601 or err.message == "Unhandled method connect":
                # Legacy server without `connect`; fall back to `ping`. A token, if any,
                # is silently dropped — the legacy server can't enforce one.
                used_fallback_ping = True
                ping_result = await self.ping()
                server_version = ping_result.protocol_version
            else:
                raise

        if server_version is None:
            raise RuntimeError(
                "SDK protocol version mismatch: "
                f"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}"
                ", but server does not report a protocol version. "
                "Please update your server to ensure compatibility."
            )

        if server_version < _MIN_PROTOCOL_VERSION or server_version > max_version:
            raise RuntimeError(
                "SDK protocol version mismatch: "
                f"SDK supports versions {_MIN_PROTOCOL_VERSION}-{max_version}"
                f", but server reports version {server_version}. "
                "Please update your SDK or server to ensure compatibility."
            )

        self._negotiated_protocol_version = server_version
        log_timing(
            logger,
            logging.DEBUG,

View on GitHub (pinned to cd8cf15dc3)