EllanJiang/GameFramework · critical · GameFrameworkException

Initialize network channel failure.

Error message

Initialize network channel failure.

What it means

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.

Solutions

1. Check the IP address family is supported on the target platform (prefer resolving IPv4 or enable IPv6).
2. Verify sockets are available in the build target (WebGL and some consoles cannot open raw TCP sockets).
3. Catch this via NetworkChannelError (SocketError) and surface a user-facing connection failure/retry.
4. Retry Connect after the environment recovers; the channel itself does not retry.

Example fix

// before
channel.Connect(IPAddress.Parse("::1"), 8080, null); // IPv6 unsupported on device
// after
channel.Connect(IPAddress.Parse("127.0.0.1"), 8080, null); // IPv4, supported address family

if (!Socket.OSSupportsIPv4 && ipAddress.AddressFamily == AddressFamily.InterNetworkV6) throw new PlatformNotSupportedException();

try { channel.Connect(ip, port, userData); } catch (GameFrameworkException ex) when (ex.Message == "Initialize network channel failure.") { ShowConnectError(ex); }

When it happens

Trigger: 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.

Common situations: IPv6 address family unsupported on the device; socket subsystem unavailable in restricted environments (WebGL builds); custom socket injection in tests returning null.

Related errors

• Initialize network channel failure.
• You must connect first.
• Socket is not active.
• Packet is invalid.
• Serialized packet failure.

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

Appendix: source

Thrown at GameFramework/Network/NetworkManager.TcpNetworkChannel.cs:68

            /// 连接到远程主机。
            /// </summary>
            /// <param name="ipAddress">远程主机的 IP 地址。</param>
            /// <param name="port">远程主机的端口号。</param>
            /// <param name="userData">用户自定义数据。</param>
            public override void Connect(IPAddress ipAddress, int port, object userData)
            {
                base.Connect(ipAddress, port, userData);
                m_Socket = new Socket(ipAddress.AddressFamily, SocketType.Stream, ProtocolType.Tcp);
                if (m_Socket == null)
                {
                    string errorMessage = "Initialize network channel failure.";
                    if (NetworkChannelError != null)
                    {
                        NetworkChannelError(this, NetworkErrorCode.SocketError, SocketError.Success, errorMessage);
                        return;
                    }

                    throw new GameFrameworkException(errorMessage);
                }

                m_NetworkChannelHelper.PrepareForConnecting();
                ConnectAsync(ipAddress, port, userData);
            }

            protected override bool ProcessSend()
            {
                if (base.ProcessSend())
                {
                    SendAsync();
                    return true;
                }

                return false;
            }

            private void ConnectAsync(IPAddress ipAddress, int port, object userData)

View on GitHub (pinned to d0c010b051)