{"record":{"id":"445626262e9dc507","repo":"XTLS/Xray-core","slug":"unknown-address-family-family","errorCode":null,"errorMessage":"unknown address family{family}","messagePattern":"unknown address family(.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"common/protocol/address.go","lineNumber":231,"sourceCode":"\t\tif maybeIPPrefix(domain[0]) {\n\t\t\taddr := net.ParseAddress(domain)\n\t\t\tif addr.Family().IsIP() {\n\t\t\t\treturn addr, nil\n\t\t\t}\n\t\t}\n\t\tif !isValidDomain(domain) {\n\t\t\treturn nil, errors.New(\"invalid domain name: \", domain)\n\t\t}\n\t\treturn net.DomainAddress(domain), nil\n\tdefault:\n\t\tpanic(\"impossible case\")\n\t}\n}\n\nfunc (p *addressParser) writeAddress(writer io.Writer, address net.Address) error {\n\ttb := p.addrByteMap[address.Family()]\n\tif tb == afInvalid {\n\t\treturn errors.New(\"unknown address family\", address.Family())\n\t}\n\n\tswitch address.Family() {\n\tcase net.AddressFamilyIPv4, net.AddressFamilyIPv6:\n\t\tif _, err := writer.Write([]byte{tb}); err != nil {\n\t\t\treturn err\n\t\t}\n\t\tif _, err := writer.Write(address.IP()); err != nil {\n\t\t\treturn err\n\t\t}\n\tcase net.AddressFamilyDomain:\n\t\tdomain := address.Domain()\n\t\tif isDomainTooLong(domain) {\n\t\t\treturn errors.New(\"Super long domain is not supported: \", domain)\n\t\t}\n\n\t\tif _, err := writer.Write([]byte{tb, byte(len(domain))}); err != nil {\n\t\t\treturn err","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/XTLS/Xray-core/blob/7d214f8b094f75322fa3990f8aadad1c912f24f5/common/protocol/address.go#L213-L249","documentation":"Returned by writeAddress when the address family of the address being serialized has no byte mapping in addrByteMap (afInvalid). The writer cannot encode an address whose family the protocol header format does not define (only IPv4, IPv6, and Domain are encodable).","triggerScenarios":"Serializing a net.Address whose Family() is neither IPv4, IPv6, nor Domain - e.g. an invalid/zero-value Address, or a future family type - into a proxy protocol header.","commonSituations":"Passing an uninitialized net.Address or an address built from invalid input into routing/forwarding code that then writes it into a protocol header.","solutions":["Check address.IsValid()/family before serializing and reject invalid addresses upstream","Ensure addresses are always constructed via net.ParseAddress or net.DomainAddress rather than raw structs"],"exampleFix":"// before\nparser.WriteAddress(writer, addr) // addr may be zero-value\n\n// after\nif !addr.IsValid() {\n    return errors.New(\"cannot serialize invalid address\")\n}\nparser.WriteAddress(writer, addr)","handlingStrategy":"type-guard","validationCode":null,"typeGuard":"func isEncodableAddress(a net.Address) bool {\n    f := a.Family()\n    return f.IsIP() || f.IsDomain()\n}","tryCatchPattern":null,"preventionTips":["Construct addresses only via net.ParseAddress/net.DomainAddress","Check IsValid() before forwarding into protocol writers"],"tags":["protocol","serialization","validation"],"backgroundTag":null,"analyzedSha":"7d214f8b094f75322fa3990f8aadad1c912f24f5","analyzedAt":"2026-08-15T14:26:24.325Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}