EllanJiang/GameFramework · error · GameFrameworkException

Packet header is invalid.

Error message

Packet header is invalid.

What it means

ProcessPacketHeader asks the INetworkChannelHelper's DeserializePacketHeader to build an IPacketHeader from received bytes. If that fails (or returns null semantics) the channel throws GameFrameworkException (or fires NetworkChannelError with NetworkErrorCode.DeserializePacketHeaderError). The received header bytes could not be parsed into a valid packet header.

Solutions

1. Verify client and server use the identical packet header layout (field order, sizes, endianness).
2. Fix/robustify DeserializePacketHeader in your INetworkChannelHelper to validate bytes before parsing.
3. Check the header handler class registered with the NetworkChannel matches the server protocol version.
4. Register NetworkChannelError for NetworkErrorCode.DeserializePacketHeaderError and close/reconnect the channel on failure.

Example fix

// before
// server uses 4-byte length, client helper reads 2-byte length
// after
int packetLength = BitConverter.ToInt32(headerBytes, 0); // match server layout

networkManager.NetworkChannelError += (channel, code, socketError, msg) => { if (code == NetworkErrorCode.DeserializePacketHeaderError) { channel.Close(); ReconnectLater(); } };

When it happens

Trigger: Received bytes not matching the expected header format (wrong packet length fields, corrupted stream); server and client using different header protocols; the helper's DeserializePacketHeader returning null/false on malformed input.

Common situations: Client talking to a server built with a different protocol version; byte-order (endianness) or header-size mismatch between custom helpers; data corruption or a proxy/intermediary mangling the stream.

Related errors

• Packet header is invalid.
• Target length is invalid.
• You must connect first.
• Socket is not active.
• Packet is invalid.

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

Appendix: source

Thrown at GameFramework/Network/NetworkManager.NetworkChannelBase.cs:568

                {
                    object customErrorData = null;
                    IPacketHeader packetHeader = m_NetworkChannelHelper.DeserializePacketHeader(m_ReceiveState.Stream, out customErrorData);

                    if (customErrorData != null && NetworkChannelCustomError != null)
                    {
                        NetworkChannelCustomError(this, customErrorData);
                    }

                    if (packetHeader == null)
                    {
                        string errorMessage = "Packet header is invalid.";
                        if (NetworkChannelError != null)
                        {
                            NetworkChannelError(this, NetworkErrorCode.DeserializePacketHeaderError, SocketError.Success, errorMessage);
                            return false;
                        }

                        throw new GameFrameworkException(errorMessage);
                    }

                    m_ReceiveState.PrepareForPacket(packetHeader);
                    if (packetHeader.PacketLength <= 0)
                    {
                        bool processSuccess = ProcessPacket();
                        m_ReceivedPacketCount++;
                        return processSuccess;
                    }
                }
                catch (Exception exception)
                {
                    m_Active = false;
                    if (NetworkChannelError != null)
                    {
                        SocketException socketException = exception as SocketException;
                        NetworkChannelError(this, NetworkErrorCode.DeserializePacketHeaderError, socketException != null ? socketException.SocketErrorCode : SocketError.Success, exception.ToString());
                        return false;

View on GitHub (pinned to d0c010b051)