{"record":{"id":"d580df20bfac2713","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-d580df","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions %d-%d, but server reports version %d. Please update your SDK or server to ensure compatibility","messagePattern":"SDK protocol version mismatch: SDK supports versions (.+?)-(.+?), but server reports version (.+?)\\. Please update your SDK or server to ensure compatibility","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/client.go","lineNumber":2029,"sourceCode":"\t\t\tserverVersion = pingResult.ProtocolVersion\n\t\t} else {\n\t\t\treturn err\n\t\t}\n\t} else {\n\t\tvar connectResult rpc.ConnectResult\n\t\tif err := json.Unmarshal(rawConnectResult, &connectResult); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tv := int(connectResult.ProtocolVersion)\n\t\tserverVersion = &v\n\t}\n\n\tif serverVersion == nil {\n\t\treturn 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)\n\t}\n\n\tif *serverVersion < minProtocolVersion || *serverVersion > maxVersion {\n\t\treturn 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)\n\t}\n\n\tc.negotiatedProtocolVersion = *serverVersion\n\treturn nil\n}\n\ntype connectHandshakeRequest struct {\n\tToken                           *string                `json:\"token,omitempty\"`\n\tEnableGitHubTelemetryForwarding *bool                  `json:\"enableGitHubTelemetryForwarding,omitempty\"`\n\tClientInfo                      *rpc.ConnectClientInfo `json:\"clientInfo,omitempty\"`\n\tSupportedTaskKinds              []rpc.TaskKind         `json:\"supportedTaskKinds,omitempty\"`\n}\n\n// stderrBufferSize is the maximum number of bytes kept from the CLI process's\n// stderr. Only the tail is retained so that memory stays bounded even when the\n// process produces a large amount of diagnostic output.\nconst stderrBufferSize = 64 * 1024\n","sourceCodeStart":2011,"sourceCodeEnd":2047,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/client.go#L2011-L2047","documentation":"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.","triggerScenarios":"Server reports version < minProtocolVersion (old server with new SDK) or > maxProtocolVersion (new server with old SDK) during the connect handshake.","commonSituations":"Upgrading the server/CLI without upgrading the Go SDK, vendoring a stale SDK version, or pinning dependency versions that drift from the deployed backend.","solutions":["Upgrade the Go SDK to a version whose supported range includes the server's reported version (server too new).","Downgrade/upgrade the server or CLI binary to a version within the SDK's supported range (server too old).","Check the error's reported server version and match SDK/server release notes for compatibility.","Keep SDK and CLI versions locked together in deployment (e.g. same release channel)."],"exampleFix":"// before\n// go.mod: github.com/anthropics/claude-code-sdk-go v1.2.0 (old) vs server 2.0\n\n// after\n$ go get github.com/anthropics/claude-code-sdk-go@latest\n$ go mod tidy","handlingStrategy":"validation","validationCode":"// fail fast on known-incompatible pairings\nif serverVer < sdkMinProtocolVersion || serverVer > sdkMaxProtocolVersion {\n    return fmt.Errorf(\"server protocol %d outside SDK range %d-%d\", serverVer, sdkMinProtocolVersion, sdkMaxProtocolVersion)\n}","typeGuard":null,"tryCatchPattern":"if err := client.Connect(ctx); err != nil {\n    var pm *sdk.ProtocolMismatchError\n    if errors.As(err, &pm) {\n        return fmt.Errorf(\"upgrade SDK or server: %w\", err)\n    }\n    return err\n}","preventionTips":["Upgrade the Go SDK when upgrading the server/CLI.","Record server protocol version in deployment metadata.","Use go get @latest + go mod tidy when bumping the backend.","Test connect handshake in CI against the pinned server version."],"tags":["go","protocol-version","compatibility","version-mismatch"],"backgroundTag":"incompatible-api-version","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}