{"record":{"id":"e79785e7788964dd","repo":"github/copilot-sdk","slug":"sdk-protocol-version-mismatch-sdk-supports-versio-e79785","errorCode":null,"errorMessage":"SDK protocol version mismatch: SDK supports versions %d-%d, but server does not report a protocol version. Please update your server to ensure compatibility","messagePattern":"SDK protocol version mismatch: SDK supports versions (.+?)-(.+?), but server does not report a protocol version\\. Please update your server to ensure compatibility","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"go/client.go","lineNumber":2025,"sourceCode":"\t\t\tpingResult, perr := c.Ping(ctx, \"\")\n\t\t\tif perr != nil {\n\t\t\t\treturn perr\n\t\t\t}\n\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","sourceCodeStart":2007,"sourceCodeEnd":2043,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/go/client.go#L2007-L2043","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\n# server v0.9 (no protocol version in connect response)\n\n// after\n# upgrade server/CLI so connect returns protocol_version\n$ claude --version   # ensure >= SDK min supported version","handlingStrategy":"validation","validationCode":"// check server reports a version within SDK range before heavy usage\nver := client.GetNegotiatedProtocolVersion()\nif ver == 0 {\n    return errors.New(\"server does not report a protocol version; update server\")\n}","typeGuard":null,"tryCatchPattern":"if err := client.Connect(ctx); err != nil {\n    if strings.Contains(err.Error(), \"does not report a protocol version\") {\n        return fmt.Errorf(\"server too old: %w\", err)\n    }\n    return err\n}","preventionTips":["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."],"tags":["go","protocol-version","compatibility","handshake"],"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-16T04:17:20.429Z"}