babalae/better-genshin-impact · error · InvalidDataException

不支持的实例 IPC 版本：{envelope.Version}。

Error message

不支持的实例 IPC 版本：{envelope.Version}。

What it means

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.

Source

Thrown at BetterGenshinImpact/Service/Instance/InstanceConnection.cs:220

                        batch.FirstSequence + (ulong)batch.Samples.Length - 1);
                    await WriteRelativeMouseResultAsync(
                        new RelativeMouseResult(lastSequence, handled),
                        linkedCancellationTokenSource.Token).ConfigureAwait(false);
                    continue;
                }

                if (frame.Value.PayloadType == InstanceIpcPayloadType.RelativeMouseResult)
                {
                    _owner.ReceiveRelativeMouseResult(
                        this,
                        InstanceIpcProtocol.ReadRelativeMouseResult(frame.Value));
                    continue;
                }

                var envelope = InstanceIpcProtocol.ReadJson(frame.Value);
                if (envelope.Version != InstanceIpcProtocol.Version)
                {
                    throw new InvalidDataException($"不支持的实例 IPC 版本：{envelope.Version}。");
                }

                if (envelope.Operation == InstanceOperations.Response)
                {
                    if (_pendingRequests.TryGetValue(envelope.RequestId, out var completionSource))
                    {
                        completionSource.TrySetResult(envelope);
                    }
                    continue;
                }

                var response = await _owner.HandleRequestAsync(
                    this,
                    envelope,
                    linkedCancellationTokenSource.Token).ConfigureAwait(false);
                if (response is not null)
                {
                    await WriteJsonAsync(response, linkedCancellationTokenSource.Token).ConfigureAwait(false);

View on GitHub (pinned to a7cb36712d)

Solutions

1. Close all BetterGI processes (root and all child/session instances) and relaunch from the same build.
2. Ensure only one BetterGI version is installed; remove stale binaries that could be picked up by the Child Session launcher.
3. Verify the installed build matches across all launch paths (direct exe and dotnet run).

// After reading the envelope, gate on version before processing.
var envelope = InstanceIpcProtocol.ReadJson(frame.Value);
if (envelope.Version != InstanceIpcProtocol.Version)
{
    throw new InvalidDataException($"不支持的实例 IPC 版本：{envelope.Version}。");
}

try
{
    var envelope = InstanceIpcProtocol.ReadJson(frame.Value);
}
catch (InvalidDataException ex) when (ex.Message.Contains("IPC 版本"))
{
    logger.LogError(ex, "IPC version mismatch; restart all instances on the same build");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• 根实例拒绝连接。
• 根实例连接响应缺少数据。
• 预期 JSON 帧，实际为 {frame.PayloadType}。
• 命名管道 JSON 消息为空。
• 预期相对鼠标帧，实际为 {frame.PayloadType}。

AI-assisted analysis of babalae/better-genshin-impact@a7cb36712d (2026-08-13). Data as JSON: /api/errors/ff71de2658132d6e. Report an issue: GitHub.