babalae/better-genshin-impact · error · InvalidDataException

预期 JSON 帧，实际为 {frame.PayloadType}。

Error message

预期 JSON 帧，实际为 {frame.PayloadType}。

What it means

Thrown by InstanceIpcProtocol.ReadJson when the frame's PayloadType is not Utf8Json. ReadJson expects a JSON envelope but received a binary frame (RelativeMouseBatch or RelativeMouseResult). This indicates the receive-loop frame dispatch is out of sync with what the peer actually sent.

Source

Thrown at BetterGenshinImpact/Service/Instance/InstanceIpcProtocol.cs:138

    internal static async ValueTask WriteJsonAsync(
        Stream stream,
        InstanceIpcEnvelope envelope,
        CancellationToken cancellationToken)
    {
        var payload = Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(envelope, SerializerSettings));
        await WriteFrameAsync(
            stream,
            InstanceIpcPayloadType.Utf8Json,
            payload,
            cancellationToken).ConfigureAwait(false);
    }

    internal static InstanceIpcEnvelope ReadJson(InstanceIpcFrame frame)
    {
        if (frame.PayloadType != InstanceIpcPayloadType.Utf8Json)
        {
            throw new InvalidDataException($"预期 JSON 帧，实际为 {frame.PayloadType}。");
        }

        return JsonConvert.DeserializeObject<InstanceIpcEnvelope>(
                   Encoding.UTF8.GetString(frame.Payload),
                   SerializerSettings)
               ?? throw new InvalidDataException("命名管道 JSON 消息为空。");
    }

    internal static async ValueTask WriteRelativeMouseBatchAsync(
        Stream stream,
        ulong firstSequence,
        IReadOnlyList<RelativeMouseSample> samples,
        CancellationToken cancellationToken)
    {
        if (samples.Count is <= 0 or > 64)
        {
            throw new ArgumentOutOfRangeException(nameof(samples), "相对鼠标批次必须包含 1 到 64 个样本。");
        }

View on GitHub (pinned to a7cb36712d)

Solutions

1. Restart both BetterGI instances so they re-establish a clean pipe session.
2. Ensure both instances run the same BetterGI build to rule out dispatch-logic differences.
3. If it reproduces on the same build, capture a trace of the raw frames — this is a dispatch-logic bug.

if (frame.PayloadType != InstanceIpcPayloadType.Utf8Json)
{
    throw new InvalidDataException($"预期 JSON 帧，实际为 {frame.PayloadType}。");
}

static bool IsJsonFrame(InstanceIpcFrame frame) => frame.PayloadType == InstanceIpcPayloadType.Utf8Json;

try
{
    var envelope = InstanceIpcProtocol.ReadJson(frame.Value);
}
catch (InvalidDataException ex) when (ex.Message.Contains("预期 JSON 帧"))
{
    logger.LogError(ex, "Frame type mismatch in JSON reader; restart instances");
}

When it happens

Trigger: A frame ordering/state-machine desync: the receive loop routes a frame to ReadJson when the peer sent a different payload type, or a peer implementation sends an unexpected frame type on the JSON channel.

Common situations: Protocol version skew between root and child; a peer bug that writes the wrong payload-type byte; in rare cases, stream corruption causing the dispatch to misroute.

Related errors

• 命名管道 JSON 消息为空。
• 根实例连接响应缺少数据。
• 预期相对鼠标帧，实际为 {frame.PayloadType}。
• 相对鼠标帧头不完整。
• 相对鼠标帧长度无效。

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