{"record":{"id":"36f98de8e9fc3914","repo":"EllanJiang/GameFramework","slug":"packet-handler-is-invalid","errorCode":null,"errorMessage":"Packet handler is invalid.","messagePattern":"Packet handler is invalid\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Network/NetworkManager.NetworkChannelBase.cs","lineNumber":301,"sourceCode":"            /// <summary>\n            /// 关闭网络频道。\n            /// </summary>\n            public virtual void Shutdown()\n            {\n                Close();\n                m_ReceivePacketPool.Shutdown();\n                m_NetworkChannelHelper.Shutdown();\n            }\n\n            /// <summary>\n            /// 注册网络消息包处理函数。\n            /// </summary>\n            /// <param name=\"handler\">要注册的网络消息包处理函数。</param>\n            public void RegisterHandler(IPacketHandler handler)\n            {\n                if (handler == null)\n                {\n                    throw new GameFrameworkException(\"Packet handler is invalid.\");\n                }\n\n                m_ReceivePacketPool.Subscribe(handler.Id, handler.Handle);\n            }\n\n            /// <summary>\n            /// 设置默认事件处理函数。\n            /// </summary>\n            /// <param name=\"handler\">要设置的默认事件处理函数。</param>\n            public void SetDefaultHandler(EventHandler<Packet> handler)\n            {\n                m_ReceivePacketPool.SetDefaultHandler(handler);\n            }\n\n            /// <summary>\n            /// 连接到远程主机。\n            /// </summary>\n            /// <param name=\"ipAddress\">远程主机的 IP 地址。</param>","sourceCodeStart":283,"sourceCodeEnd":319,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Network/NetworkManager.NetworkChannelBase.cs#L283-L319","documentation":"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.","triggerScenarios":"Calling networkChannel.RegisterHandler(null), typically when the handler object was never constructed, a Unity component lookup failed, or a DI/factory returned null.","commonSituations":"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.","solutions":["Pass a constructed handler instance, e.g. channel.RegisterHandler(new MyPacketHandler()).","Ensure handler MonoBehaviours are attached to the network agent object before registration.","Assert handler != null at the call site to catch wiring problems earlier with context."],"exampleFix":"// before\nIPacketHandler handler = handlerRoot.GetComponent<MyHandler>() as IPacketHandler; // null\nm_Channel.RegisterHandler(handler);\n\n// after\nvar handler = handlerRoot.GetComponent<MyHandler>() as IPacketHandler ?? new MyHandler();\nm_Channel.RegisterHandler(handler);","handlingStrategy":"validation","validationCode":"if (handler != null)\n    channel.RegisterHandler(handler);\nelse\n    Log.Error(\"Packet handler not constructed\");","typeGuard":"static bool IsValidHandler(IPacketHandler h) => h != null;","tryCatchPattern":"try { channel.RegisterHandler(handler); }\ncatch (GameFrameworkException ex) { Log.Error(\"Handler registration failed: \" + ex.Message); }","preventionTips":["Construct handler instances explicitly before registration.","Verify handler MonoBehaviours exist on the network object (GetComponent result null-checked).","Register all handlers in one bootstrap method so missing wiring is caught together."],"tags":["network","null-argument","packet-handler"],"backgroundTag":"null-argument","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}