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

What it means

After the handshake the SDK compares the server's reported protocol version against its supported range [_MIN_PROTOCOL_VERSION, max_version]. If the server version is older or newer than the SDK supports, this RuntimeError is raised advising to update the SDK or server.

Solutions

  1. Compare the reported server version in the message to your SDK's supported range and upgrade whichever side is stale
  2. pip install --upgrade the Copilot SDK when the server is newer
  3. Update the Copilot CLI binary when the server is older than the SDK's minimum
  4. Pin CLI auto-update and SDK versions together in CI to keep them in lockstep

Example fix

// before
pip install copilot==0.1.0  # old SDK vs auto-updated CLI
// after
pip install --upgrade copilot  # or pin: copilot==X matching CLI version X
Defensive patterns

Strategy: fallback

Validate before calling

# compare CLI and SDK versions before connecting
import subprocess
cli_ver = subprocess.run([cli_path, "--version"], capture_output=True, text=True).stdout.strip()
import copilot
print(cli_ver, copilot.__version__)  # keep in lockstep

Try / catch

try:
    await client.start()
except RuntimeError as e:
    if "protocol version mismatch" in str(e):
        # upgrade SDK and/or CLI, then retry
        raise SystemExit("update SDK or CLI and retry")
    raise

Prevention

When it happens

Trigger: Connecting when server_version < _MIN_PROTOCOL_VERSION (very old server) or server_version > max_version (server newer than the installed SDK), as reported in the 'connect'/'ping' response.

Common situations: SDK pip package lagging behind an auto-updated CLI (server too new); a very old CLI paired with a current SDK (server too old); mixed-version environments where different machines install CLI and SDK independently.

Related errors

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

Appendix: source

Thrown at python/copilot/client.py:4149

            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,
            "CopilotClient._verify_protocol_version protocol handshake complete",
            handshake_start,
            protocol_version=server_version,
            used_fallback_ping=used_fallback_ping,
        )

    def _convert_provider_to_wire_format(
        self, provider: ProviderConfig | dict[str, Any]

View on GitHub (pinned to cd8cf15dc3)