EllanJiang/GameFramework · error · GameFrameworkException

Packet header length is invalid.

Error message

Packet header length is invalid.

What it means

The network channel helper's PacketHeaderLength must be zero or positive because it determines how many bytes are read to learn each packet's size. A negative value is meaningless, so CreateNetworkChannel throws immediately. The guard validates the helper contract before any channel is constructed.

Solutions

1. Fix the helper's PacketHeaderLength to return a non-negative byte count matching your protocol header size
2. If the value is configurable, clamp or validate it at helper initialization time
3. Inspect the helper implementation for sentinel values like -1

Example fix

// before
public int PacketHeaderLength => _headerLength; // _headerLength never set (-1)
// after
public int PacketHeaderLength => _headerLength >= 0 ? _headerLength : 4;

if (helper.PacketHeaderLength < 0) throw new InvalidOperationException("PacketHeaderLength must be >= 0");
var channel = networkManager.CreateNetworkChannel(name, serviceType, helper);

bool HasValidHeaderLength(INetworkChannelHelper h) => h != null && h.PacketHeaderLength >= 0;

try { var channel = networkManager.CreateNetworkChannel(name, serviceType, helper); }
catch (GameFrameworkException ex) { Log.Error("Invalid packet header length: {0}", ex.Message); }

When it happens

Trigger: A custom INetworkChannelHelper implementation returns a negative value from its PacketHeaderLength property, often due to an uninitialized backing field or an inverted sign in a computed header size.

Common situations: Writing a custom packet protocol helper and accidentally returning -1 as a 'not set' sentinel; copying a helper template and hard-coding the wrong constant; struct field never initialized before use.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• You must connect first.
• Socket is not active.
• Packet is invalid.
• Serialized packet failure.
• Packet header is invalid.

AI-assisted analysis of EllanJiang/GameFramework@d0c010b051 (2026-09-15). Data as JSON: /api/errors/de0648d618bcbb87. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Network/NetworkManager.cs:234

        }

        /// <summary>
        /// 创建网络频道。
        /// </summary>
        /// <param name="name">网络频道名称。</param>
        /// <param name="serviceType">网络服务类型。</param>
        /// <param name="networkChannelHelper">网络频道辅助器。</param>
        /// <returns>要创建的网络频道。</returns>
        public INetworkChannel CreateNetworkChannel(string name, ServiceType serviceType, INetworkChannelHelper networkChannelHelper)
        {
            if (networkChannelHelper == null)
            {
                throw new GameFrameworkException("Network channel helper is invalid.");
            }

            if (networkChannelHelper.PacketHeaderLength < 0)
            {
                throw new GameFrameworkException("Packet header length is invalid.");
            }

            if (HasNetworkChannel(name))
            {
                throw new GameFrameworkException(Utility.Text.Format("Already exist network channel '{0}'.", name ?? string.Empty));
            }

            NetworkChannelBase networkChannel = null;
            switch (serviceType)
            {
                case ServiceType.Tcp:
                    networkChannel = new TcpNetworkChannel(name, networkChannelHelper);
                    break;

                case ServiceType.TcpWithSyncReceive:
                    networkChannel = new TcpWithSyncReceiveNetworkChannel(name, networkChannelHelper);
                    break;

View on GitHub (pinned to d0c010b051)