{"record":{"id":"857c83ebc2ca0851","repo":"babalae/better-genshin-impact","slug":"header-sizeof-uint","errorCode":null,"errorMessage":"未知命名管道载荷类型：{header[sizeof(uint)]}。","messagePattern":"未知命名管道载荷类型：(.+?)。","errorType":"exception","errorClass":"InvalidDataException","httpStatus":null,"severity":"error","filePath":"BetterGenshinImpact/Service/Instance/InstanceIpcProtocol.cs","lineNumber":304,"sourceCode":"    {\n        var header = new byte[FrameHeaderLength];\n        var firstRead = await stream.ReadAsync(header.AsMemory(0, 1), cancellationToken).ConfigureAwait(false);\n        if (firstRead == 0)\n        {\n            return null;\n        }\n\n        await stream.ReadExactlyAsync(header.AsMemory(1), cancellationToken).ConfigureAwait(false);\n        var payloadLength = BinaryPrimitives.ReadUInt32LittleEndian(header);\n        if (payloadLength > MaxPayloadLength)\n        {\n            throw new InvalidDataException($\"命名管道消息超过 {MaxPayloadLength} 字节限制。\");\n        }\n\n        var payloadType = (InstanceIpcPayloadType)header[sizeof(uint)];\n        if (!Enum.IsDefined(payloadType))\n        {\n            throw new InvalidDataException($\"未知命名管道载荷类型：{header[sizeof(uint)]}。\");\n        }\n\n        var payload = new byte[checked((int)payloadLength)];\n        if (payload.Length > 0)\n        {\n            await stream.ReadExactlyAsync(payload, cancellationToken).ConfigureAwait(false);\n        }\n\n        return new InstanceIpcFrame(payloadType, payload);\n    }\n\n    private static async ValueTask WriteFrameAsync(\n        Stream stream,\n        InstanceIpcPayloadType payloadType,\n        ReadOnlyMemory<byte> payload,\n        CancellationToken cancellationToken)\n    {\n        if (payload.Length > MaxPayloadLength)","sourceCodeStart":286,"sourceCodeEnd":322,"githubUrl":"https://github.com/babalae/better-genshin-impact/blob/a7cb36712dcb409be610257d877fcea3597e9d6b/BetterGenshinImpact/Service/Instance/InstanceIpcProtocol.cs#L286-L322","documentation":"Thrown by ReadFrameAsync after the payload length check passes. The 5th byte of the frame header is cast to InstanceIpcPayloadType and validated via Enum.IsDefined. If the byte value is not 1 (Utf8Json), 2 (RelativeMouseBatch), or 3 (RelativeMouseResult), the frame type is unrecognized and rejected.","triggerScenarios":"The payload type byte in the frame header is 0 or >= 4. This occurs when a newer protocol version introduced a new payload type that this receiver does not know about, when the stream is misaligned so a payload data byte is interpreted as the type field, or when the pipe buffer contains residual data from a crashed previous session.","commonSituations":"Running mixed versions of BetterGI where one side was updated to send a new frame type; stream misalignment caused by a bug in the receive loop reading the wrong number of bytes; a security tool or pipe relay injecting or dropping bytes; Windows named pipe kernel buffer not fully flushed after a previous process crash.","solutions":["Ensure all BetterGI instances (Primary, ChildSession, WebView) in the same user session run the same application version.","Catch InvalidDataException in the receive loop and dispose the connection to trigger a clean reconnect.","Log the raw type byte value alongside the frame to identify whether it is a version issue (consistent new value) or corruption (random values).","If developing a new payload type, update InstanceIpcPayloadType in all peers before deploying."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"// Check if a payload type byte is a known type\nstatic bool IsKnownPayloadType(byte typeByte)\n    => Enum.IsDefined((InstanceIpcPayloadType)typeByte);","tryCatchPattern":"try\n{\n    var frame = await InstanceIpcProtocol.ReadFrameAsync(stream, ct);\n}\ncatch (InvalidDataException ex) when (ex.Message.Contains(\"未知命名管道载荷类型\"))\n{\n    _logger.LogError(ex, \"收到未知帧类型，可能是版本不兼容，关闭连接\");\n    await connection.DisposeAsync();\n}","preventionTips":["Run all BetterGI instances in the same user session at the same version.","Update InstanceIpcPayloadType in all peers before deploying a new frame type.","Close the connection on unknown frame types — do not attempt to skip or resync the stream manually."],"tags":["ipc","named-pipe","binary-protocol","frame-validation","version-mismatch"],"backgroundTag":null,"analyzedSha":"a7cb36712dcb409be610257d877fcea3597e9d6b","analyzedAt":"2026-08-13T16:44:57.548Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}