EllanJiang/GameFramework · critical · GameFrameworkException

Initialize network channel failure.

Error message

Initialize network channel failure.

What it means

Identical to the TcpNetworkChannel guard but in TcpWithSyncReceiveNetworkChannel.Connect: the Socket created for the synchronous-receive TCP channel was null, so GameFramework throws GameFrameworkException (or fires NetworkChannelError with NetworkErrorCode.SocketError). The channel cannot proceed to ConnectAsync without a socket.

Solutions

1. Use an IPv4 address or ensure the OS/device supports the requested AddressFamily.
2. Confirm the target platform supports TCP sockets (not WebGL); switch to the async TcpNetworkChannel where appropriate.
3. Handle NetworkChannelError (SocketError) with a user-visible failure and retry flow.
4. Check that no custom socket replacement/factory is returning null.

Example fix

// before
syncChannel.Connect(ipAddress, port, userData); // socket allocation failed
// after
try { syncChannel.Connect(ipAddress, port, userData); }
catch (GameFrameworkException) { ShowConnectionError(); }

if (!Socket.OSSupportsIPv4 && !Socket.OSSupportsIPv6) return false; // sockets unavailable

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

When it happens

Trigger: new Socket(addressFamily, Stream, Tcp) failing/returning null in the sync-receive channel variant; unsupported address family; platform without TCP socket support.

Common situations: Using the sync-receive channel on platforms where socket allocation fails; IPv6-only addresses on IPv4-only devices; restricted sandbox environments.

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/53ffa8a2ff7e7900. Report an issue: GitHub.

Appendix: source

Thrown at GameFramework/Network/NetworkManager.TcpWithSyncReceiveNetworkChannel.cs:66

            /// 连接到远程主机。
            /// </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;
            }

            protected override void ProcessReceive()

View on GitHub (pinned to d0c010b051)