{"record":{"id":"69c00b8cd802257b","repo":"EllanJiang/GameFramework","slug":"initialize-network-channel-failure","errorCode":null,"errorMessage":"Initialize network channel failure.","messagePattern":"Initialize network channel failure\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"critical","filePath":"GameFramework/Network/NetworkManager.TcpNetworkChannel.cs","lineNumber":68,"sourceCode":"            /// 连接到远程主机。\n            /// </summary>\n            /// <param name=\"ipAddress\">远程主机的 IP 地址。</param>\n            /// <param name=\"port\">远程主机的端口号。</param>\n            /// <param name=\"userData\">用户自定义数据。</param>\n            public override void Connect(IPAddress ipAddress, int port, object userData)\n            {\n                base.Connect(ipAddress, port, userData);\n                m_Socket = new Socket(ipAddress.AddressFamily, SocketType.Stream, ProtocolType.Tcp);\n                if (m_Socket == null)\n                {\n                    string errorMessage = \"Initialize network channel failure.\";\n                    if (NetworkChannelError != null)\n                    {\n                        NetworkChannelError(this, NetworkErrorCode.SocketError, SocketError.Success, errorMessage);\n                        return;\n                    }\n\n                    throw new GameFrameworkException(errorMessage);\n                }\n\n                m_NetworkChannelHelper.PrepareForConnecting();\n                ConnectAsync(ipAddress, port, userData);\n            }\n\n            protected override bool ProcessSend()\n            {\n                if (base.ProcessSend())\n                {\n                    SendAsync();\n                    return true;\n                }\n\n                return false;\n            }\n\n            private void ConnectAsync(IPAddress ipAddress, int port, object userData)","sourceCodeStart":50,"sourceCodeEnd":86,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Network/NetworkManager.TcpNetworkChannel.cs#L50-L86","documentation":"TcpNetworkChannel.Connect creates the underlying Socket (new Socket(addressFamily, Stream, Tcp)); if the Socket constructor yields null (allocation failure in the custom socket implementation / platform restriction), the channel throws GameFrameworkException (or fires NetworkChannelError with NetworkErrorCode.SocketError). It is an initialization-failure guard before starting the async connect.","triggerScenarios":"new Socket(...) returning null (rare; platform/embedded socket factory failure); unsupported AddressFamily for the target IP; running on a platform where TCP sockets are unavailable or the IL2CPP/native socket layer failed to init.","commonSituations":"IPv6 address family unsupported on the device; socket subsystem unavailable in restricted environments (WebGL builds); custom socket injection in tests returning null.","solutions":["Check the IP address family is supported on the target platform (prefer resolving IPv4 or enable IPv6).","Verify sockets are available in the build target (WebGL and some consoles cannot open raw TCP sockets).","Catch this via NetworkChannelError (SocketError) and surface a user-facing connection failure/retry.","Retry Connect after the environment recovers; the channel itself does not retry."],"exampleFix":"// before\nchannel.Connect(IPAddress.Parse(\"::1\"), 8080, null); // IPv6 unsupported on device\n// after\nchannel.Connect(IPAddress.Parse(\"127.0.0.1\"), 8080, null); // IPv4, supported address family","handlingStrategy":"try-catch","validationCode":"if (!Socket.OSSupportsIPv4 && ipAddress.AddressFamily == AddressFamily.InterNetworkV6) throw new PlatformNotSupportedException();","typeGuard":null,"tryCatchPattern":"try { channel.Connect(ip, port, userData); } catch (GameFrameworkException ex) when (ex.Message == \"Initialize network channel failure.\") { ShowConnectError(ex); }","preventionTips":["Verify socket support on every target platform before shipping","Prefer IPv4 or resolve addresses to a supported family","Register NetworkChannelError to convert this into a UI-visible failure","Add a connection-retry with backoff in the game layer"],"tags":["network","tcp","socket-init","gameframework"],"backgroundTag":"module-init-failed","analyzedSha":"d0c010b05167c58e92350449d04864a91ca13fd2","analyzedAt":"2026-09-15T13:37:15.352Z","contentChangedAt":"2026-09-15T13:37:15.352Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}