SDK protocol version mismatch: SDK supports versions

Error message

SDK protocol version mismatch: SDK supports versions %d-%d, but server does not report a protocol version. Please update your server to ensure compatibility

What it means

During the connect handshake the server did not report any protocol version, so the SDK cannot verify compatibility and fails with this mismatch error. The SDK supports a range [minProtocolVersion, maxProtocolVersion]; a server without a version field is treated as too old to trust. This guards against silently using incompatible RPCs.

Solutions

Update the server/CLI binary to a version that reports a protocol version in the connect response.
If you must support the legacy server, pin/upgrade the SDK version that matches its behavior.
Inspect the handshake response to confirm the protocol version field is present and not stripped by middleware.
Align deployment so server and SDK are upgraded together.

Example fix

// before
# server v0.9 (no protocol version in connect response)

// after
# upgrade server/CLI so connect returns protocol_version
$ claude --version   # ensure >= SDK min supported version

Defensive patterns

Strategy: validation

Validate before calling

// check server reports a version within SDK range before heavy usage
ver := client.GetNegotiatedProtocolVersion()
if ver == 0 {
    return errors.New("server does not report a protocol version; update server")
}

Try / catch

if err := client.Connect(ctx); err != nil {
    if strings.Contains(err.Error(), "does not report a protocol version") {
        return fmt.Errorf("server too old: %w", err)
    }
    return err
}

Prevention

Deploy server/CLI versions that report protocol_version.
Check --version of the CLI during deployment health checks.
Avoid third-party servers that omit the version field.
Pin SDK and server to matching release channels.

When it happens

Trigger: The `connect` (or legacy `ping`) handshake response contains no protocol version field — e.g. a legacy/unknown server build that predates version reporting, or a non-official server implementation.

Common situations: Pointing the SDK at an outdated CLI/server binary, running a custom or third-party backend that omits protocol_version, or a proxy stripping response fields.

Related errors

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

Appendix: source

Thrown at go/client.go:2025

			pingResult, perr := c.Ping(ctx, "")
			if perr != nil {
				return perr
			}
			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

View on GitHub (pinned to cd8cf15dc3)