github/copilot-sdk · error

SDK protocol version mismatch: SDK supports versions

Error message

SDK protocol version mismatch: SDK supports versions %d-%d, but server reports version %d. Please update your SDK or server to ensure compatibility

What it means

The handshake succeeded and the server reported a protocol version, but it lies outside the SDK's supported range [minProtocolVersion, maxProtocolVersion]. The SDK refuses to connect to avoid undefined behavior from incompatible RPC semantics. Either the server is too old (below min) or too new (above max) for this SDK build.

Solutions

  1. Upgrade the Go SDK to a version whose supported range includes the server's reported version (server too new).
  2. Downgrade/upgrade the server or CLI binary to a version within the SDK's supported range (server too old).
  3. Check the error's reported server version and match SDK/server release notes for compatibility.
  4. Keep SDK and CLI versions locked together in deployment (e.g. same release channel).

Example fix

// before
// go.mod: github.com/anthropics/claude-code-sdk-go v1.2.0 (old) vs server 2.0

// after
$ go get github.com/anthropics/claude-code-sdk-go@latest
$ go mod tidy
Defensive patterns

Strategy: validation

Validate before calling

// fail fast on known-incompatible pairings
if serverVer < sdkMinProtocolVersion || serverVer > sdkMaxProtocolVersion {
    return fmt.Errorf("server protocol %d outside SDK range %d-%d", serverVer, sdkMinProtocolVersion, sdkMaxProtocolVersion)
}

Try / catch

if err := client.Connect(ctx); err != nil {
    var pm *sdk.ProtocolMismatchError
    if errors.As(err, &pm) {
        return fmt.Errorf("upgrade SDK or server: %w", err)
    }
    return err
}

Prevention

When it happens

Trigger: Server reports version < minProtocolVersion (old server with new SDK) or > maxProtocolVersion (new server with old SDK) during the connect handshake.

Common situations: Upgrading the server/CLI without upgrading the Go SDK, vendoring a stale SDK version, or pinning dependency versions that drift from the deployed backend.

Related errors

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

Appendix: source

Thrown at go/client.go:2029

			serverVersion = pingResult.ProtocolVersion
		} else {
			return err
		}
	} else {
		var connectResult rpc.ConnectResult
		if err := json.Unmarshal(rawConnectResult, &connectResult); err != nil {
			return err
		}
		v := int(connectResult.ProtocolVersion)
		serverVersion = &v
	}

	if serverVersion == nil {
		return fmt.Errorf("SDK protocol version mismatch: SDK supports versions %d-%d, but server does not report a protocol version. Please update your server to ensure compatibility", minProtocolVersion, maxVersion)
	}

	if *serverVersion < minProtocolVersion || *serverVersion > maxVersion {
		return fmt.Errorf("SDK protocol version mismatch: SDK supports versions %d-%d, but server reports version %d. Please update your SDK or server to ensure compatibility", minProtocolVersion, maxVersion, *serverVersion)
	}

	c.negotiatedProtocolVersion = *serverVersion
	return nil
}

type connectHandshakeRequest struct {
	Token                           *string                `json:"token,omitempty"`
	EnableGitHubTelemetryForwarding *bool                  `json:"enableGitHubTelemetryForwarding,omitempty"`
	ClientInfo                      *rpc.ConnectClientInfo `json:"clientInfo,omitempty"`
	SupportedTaskKinds              []rpc.TaskKind         `json:"supportedTaskKinds,omitempty"`
}

// stderrBufferSize is the maximum number of bytes kept from the CLI process's
// stderr. Only the tail is retained so that memory stays bounded even when the
// process produces a large amount of diagnostic output.
const stderrBufferSize = 64 * 1024

View on GitHub (pinned to cd8cf15dc3)