EllanJiang/GameFramework · error · GameFrameworkException

Packet handler is invalid.

Error message

Packet handler is invalid.

What it means

NetworkChannelBase.RegisterHandler rejects a null IPacketHandler. Handlers are subscribed by packet id into the receive-packet pool (m_ReceivePacketPool.Subscribe(handler.Id, handler.Handle)); a null handler has no id or callback, so registration is impossible and the library throws immediately.

Solutions

1. Pass a constructed handler instance, e.g. channel.RegisterHandler(new MyPacketHandler()).
2. Ensure handler MonoBehaviours are attached to the network agent object before registration.
3. Assert handler != null at the call site to catch wiring problems earlier with context.

Example fix

// before
IPacketHandler handler = handlerRoot.GetComponent<MyHandler>() as IPacketHandler; // null
m_Channel.RegisterHandler(handler);

// after
var handler = handlerRoot.GetComponent<MyHandler>() as IPacketHandler ?? new MyHandler();
m_Channel.RegisterHandler(handler);

if (handler != null)
    channel.RegisterHandler(handler);
else
    Log.Error("Packet handler not constructed");

static bool IsValidHandler(IPacketHandler h) => h != null;

try { channel.RegisterHandler(handler); }
catch (GameFrameworkException ex) { Log.Error("Handler registration failed: " + ex.Message); }

When it happens

Trigger: Calling networkChannel.RegisterHandler(null), typically when the handler object was never constructed, a Unity component lookup failed, or a DI/factory returned null.

Common situations: Forgetting to new up the handler class before registration; GetComponent for a handler script that is not attached to any GameObject; conditional builds where the handler implementation is excluded.

Related errors

• Packet is invalid.
• Packet header is invalid.
• Results is invalid.
• Network channel helper is invalid.
• Data string is invalid.

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

Appendix: source

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

            /// <summary>
            /// 关闭网络频道。
            /// </summary>
            public virtual void Shutdown()
            {
                Close();
                m_ReceivePacketPool.Shutdown();
                m_NetworkChannelHelper.Shutdown();
            }

            /// <summary>
            /// 注册网络消息包处理函数。
            /// </summary>
            /// <param name="handler">要注册的网络消息包处理函数。</param>
            public void RegisterHandler(IPacketHandler handler)
            {
                if (handler == null)
                {
                    throw new GameFrameworkException("Packet handler is invalid.");
                }

                m_ReceivePacketPool.Subscribe(handler.Id, handler.Handle);
            }

            /// <summary>
            /// 设置默认事件处理函数。
            /// </summary>
            /// <param name="handler">要设置的默认事件处理函数。</param>
            public void SetDefaultHandler(EventHandler<Packet> handler)
            {
                m_ReceivePacketPool.SetDefaultHandler(handler);
            }

            /// <summary>
            /// 连接到远程主机。
            /// </summary>
            /// <param name="ipAddress">远程主机的 IP 地址。</param>

View on GitHub (pinned to d0c010b051)