{"record":{"id":"ff71de2658132d6e","repo":"babalae/better-genshin-impact","slug":"ipc-envelope-version","errorCode":null,"errorMessage":"不支持的实例 IPC 版本：{envelope.Version}。","messagePattern":"不支持的实例 IPC 版本：(.+?)。","errorType":"exception","errorClass":"InvalidDataException","httpStatus":null,"severity":"error","filePath":"BetterGenshinImpact/Service/Instance/InstanceConnection.cs","lineNumber":220,"sourceCode":"                        batch.FirstSequence + (ulong)batch.Samples.Length - 1);\n                    await WriteRelativeMouseResultAsync(\n                        new RelativeMouseResult(lastSequence, handled),\n                        linkedCancellationTokenSource.Token).ConfigureAwait(false);\n                    continue;\n                }\n\n                if (frame.Value.PayloadType == InstanceIpcPayloadType.RelativeMouseResult)\n                {\n                    _owner.ReceiveRelativeMouseResult(\n                        this,\n                        InstanceIpcProtocol.ReadRelativeMouseResult(frame.Value));\n                    continue;\n                }\n\n                var envelope = InstanceIpcProtocol.ReadJson(frame.Value);\n                if (envelope.Version != InstanceIpcProtocol.Version)\n                {\n                    throw new InvalidDataException($\"不支持的实例 IPC 版本：{envelope.Version}。\");\n                }\n\n                if (envelope.Operation == InstanceOperations.Response)\n                {\n                    if (_pendingRequests.TryGetValue(envelope.RequestId, out var completionSource))\n                    {\n                        completionSource.TrySetResult(envelope);\n                    }\n                    continue;\n                }\n\n                var response = await _owner.HandleRequestAsync(\n                    this,\n                    envelope,\n                    linkedCancellationTokenSource.Token).ConfigureAwait(false);\n                if (response is not null)\n                {\n                    await WriteJsonAsync(response, linkedCancellationTokenSource.Token).ConfigureAwait(false);","sourceCodeStart":202,"sourceCodeEnd":238,"githubUrl":"https://github.com/babalae/better-genshin-impact/blob/a7cb36712dcb409be610257d877fcea3597e9d6b/BetterGenshinImpact/Service/Instance/InstanceConnection.cs#L202-L238","documentation":"Thrown by InstanceConnection.ReceiveLoopAsync when an incoming InstanceIpcEnvelope has a Version field that does not match InstanceIpcProtocol.Version (currently 2). This is a hard compatibility gate: mismatched IPC protocol versions are rejected to prevent silent data corruption between root and child instances communicating over the named pipe.","triggerScenarios":"Two different BetterGI builds communicate over the same user pipe — e.g. the root runs build A (protocol v2) and a freshly launched Child Session instance runs build B (protocol v1 or v3). The version field is checked right after deserializing the JSON envelope.","commonSituations":"User upgraded BetterGI but a previous Child Session instance is still running the old build; user has two BetterGI installations of different versions; a child process was launched from a cached/stale binary.","solutions":["Close all BetterGI processes (root and all child/session instances) and relaunch from the same build.","Ensure only one BetterGI version is installed; remove stale binaries that could be picked up by the Child Session launcher.","Verify the installed build matches across all launch paths (direct exe and dotnet run)."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// After reading the envelope, gate on version before processing.\nvar envelope = InstanceIpcProtocol.ReadJson(frame.Value);\nif (envelope.Version != InstanceIpcProtocol.Version)\n{\n    throw new InvalidDataException($\"不支持的实例 IPC 版本：{envelope.Version}。\");\n}","typeGuard":null,"tryCatchPattern":"try\n{\n    var envelope = InstanceIpcProtocol.ReadJson(frame.Value);\n}\ncatch (InvalidDataException ex) when (ex.Message.Contains(\"IPC 版本\"))\n{\n    logger.LogError(ex, \"IPC version mismatch; restart all instances on the same build\");\n}","preventionTips":["Run a single BetterGI build across all instances (root and Child Session).","Before upgrading, close all instances to avoid a mixed-version window.","Remove stale BetterGI binaries so the Child Session launcher cannot pick up an old build."],"tags":["ipc","version","instance","compatibility","named-pipe"],"backgroundTag":null,"analyzedSha":"a7cb36712dcb409be610257d877fcea3597e9d6b","analyzedAt":"2026-08-13T16:44:57.548Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}