{"record":{"id":"9d0b1fa47c4953f5","repo":"EllanJiang/GameFramework","slug":"not-supported-address-family-0","errorCode":null,"errorMessage":"Not supported address family '{0}'.","messagePattern":"Not supported address family '(.+?)'\\.","errorType":"exception","errorClass":"GameFrameworkException","httpStatus":null,"severity":"error","filePath":"GameFramework/Network/NetworkManager.NetworkChannelBase.cs","lineNumber":358,"sourceCode":"                switch (ipAddress.AddressFamily)\n                {\n                    case System.Net.Sockets.AddressFamily.InterNetwork:\n                        m_AddressFamily = AddressFamily.IPv4;\n                        break;\n\n                    case System.Net.Sockets.AddressFamily.InterNetworkV6:\n                        m_AddressFamily = AddressFamily.IPv6;\n                        break;\n\n                    default:\n                        string errorMessage = Utility.Text.Format(\"Not supported address family '{0}'.\", ipAddress.AddressFamily);\n                        if (NetworkChannelError != null)\n                        {\n                            NetworkChannelError(this, NetworkErrorCode.AddressFamilyError, SocketError.Success, errorMessage);\n                            return;\n                        }\n\n                        throw new GameFrameworkException(errorMessage);\n                }\n\n                m_SendState.Reset();\n                m_ReceiveState.PrepareForPacketHeader(m_NetworkChannelHelper.PacketHeaderLength);\n            }\n\n            /// <summary>\n            /// 关闭连接并释放所有相关资源。\n            /// </summary>\n            public void Close()\n            {\n                lock (this)\n                {\n                    if (m_Socket == null)\n                    {\n                        return;\n                    }\n","sourceCodeStart":340,"sourceCodeEnd":376,"githubUrl":"https://github.com/EllanJiang/GameFramework/blob/d0c010b05167c58e92350449d04864a91ca13fd2/GameFramework/Network/NetworkManager.NetworkChannelBase.cs#L340-L376","documentation":"During Connect, NetworkChannelBase resolves the host address and checks its SocketAddress AddressFamily against what the socket supports. If the address family is unsupported (e.g. an IPv6-mapped/unexpected family on an IPv4-only socket), the channel raises NetworkChannelError with NetworkErrorCode.AddressFamilyError; if no error handler is subscribed, it throws the GameFrameworkException carrying 'Not supported address family {0}'.","triggerScenarios":"Calling Connect with an address whose AddressFamily is not InterNetwork/InterNetworkV6 as expected by the channel, e.g. connecting to an IPv6 literal or hostname resolving to AAAA records on a system/socket configured for IPv4 only.","commonSituations":"Dual-stack environments where a hostname resolves to IPv6 while the server only listens on IPv4; hardcoded IPv6 addresses on IPv4-only build targets; DNS changes returning a different family than during development.","solutions":["Subscribe to NetworkChannelError and handle AddressFamilyError instead of relying on the thrown exception.","Connect using an explicit IPv4 (or matching-family) address, or resolve the hostname and pick an address whose AddressFamily the channel supports.","Enable IPv6 support on the platform/socket configuration, or force IPv4 resolution (e.g. prefer A records) to match the channel."],"exampleFix":"// before\nchannel.Connect(\"example.com\", 8080); // resolves to IPv6, socket is IPv4-only, no error handler\n\n// after\nchannel.NetworkChannelError += (c, code, se, msg) => Log.Error(msg);\nvar addrs = Dns.GetHostAddresses(\"example.com\");\nvar ipv4 = Array.Find(addrs, a => a.AddressFamily == AddressFamily.InterNetwork);\nif (ipv4 != null) channel.Connect(ipv4.ToString(), 8080);","handlingStrategy":"try-catch","validationCode":"var addrs = Dns.GetHostAddresses(host);\nif (!addrs.Any(a => a.AddressFamily == AddressFamily.InterNetwork || a.AddressFamily == AddressFamily.InterNetworkV6))\n    return; // no usable address family\nchannel.Connect(host, port);","typeGuard":"static bool IsSupportedFamily(IPAddress a) => a.AddressFamily == AddressFamily.InterNetwork || a.AddressFamily == AddressFamily.InterNetworkV6;","tryCatchPattern":"channel.NetworkChannelError += (c, errorCode, socketError, msg) =>\n{\n    if (errorCode == NetworkErrorCode.AddressFamilyError)\n        Log.Error(\"Unsupported address family: \" + msg);\n};\n// and/or wrap the direct call:\ntry { channel.Connect(host, port); }\ncatch (GameFrameworkException ex) { Log.Error(\"Connect failed: \" + ex.Message); }","preventionTips":["Always subscribe NetworkChannelError before Connect so address-family problems surface as events, not exceptions.","Resolve hostnames and select an address whose family matches the channel/socket configuration.","Verify IPv6/IPv4 support on target platforms before hardcoding addresses.","Test connections in dual-stack environments where AAAA records may be preferred."],"tags":["network","socket","address-family","ipv6"],"backgroundTag":"unsupported-operation","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"}