{"record":{"id":"00429a21df586326","repo":"nats-io/nats-server","slug":"w-unsupported-address-family-0x-02x","errorCode":null,"errorMessage":"%w: unsupported address family 0x%02x","messagePattern":"%w: unsupported address family 0x%02x","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/client_proxyproto.go","lineNumber":376,"sourceCode":"\t// Parse address data based on family\n\tvar addr *proxyProtoAddr\n\tvar err error\n\tswitch family {\n\tcase proxyProtoFamilyInet:\n\t\taddr, err = parseIPv4Addr(conn, addrLen)\n\tcase proxyProtoFamilyInet6:\n\t\taddr, err = parseIPv6Addr(conn, addrLen)\n\tcase proxyProtoFamilyUnspec:\n\t\t// UNSPEC family with PROXY command is valid but rare\n\t\t// Just skip the address data\n\t\tif addrLen > 0 {\n\t\t\tif _, err := io.CopyN(io.Discard, conn, int64(addrLen)); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to discard UNSPEC address address data: %w\", err)\n\t\t\t}\n\t\t}\n\t\treturn nil, nil\n\tdefault:\n\t\treturn nil, fmt.Errorf(\"%w: unsupported address family 0x%02x\", errProxyProtoUnsupported, family)\n\t}\n\treturn addr, err\n}\n\n// parseIPv4Addr parses IPv4 address data from PROXY protocol header\nfunc parseIPv4Addr(conn net.Conn, addrLen uint16) (*proxyProtoAddr, error) {\n\t// IPv4: 4 (src IP) + 4 (dst IP) + 2 (src port) + 2 (dst port) = 12 bytes minimum\n\tif addrLen < proxyProtoAddrSizeIPv4 {\n\t\treturn nil, fmt.Errorf(\"IPv4 address data too short: %d bytes\", addrLen)\n\t}\n\taddrData := make([]byte, addrLen)\n\tif _, err := io.ReadFull(conn, addrData); err != nil {\n\t\treturn nil, fmt.Errorf(\"failed to read IPv4 address data: %w\", err)\n\t}\n\treturn &proxyProtoAddr{\n\t\tsrcIP:   net.IP(addrData[0:4]),\n\t\tdstIP:   net.IP(addrData[4:8]),\n\t\tsrcPort: binary.BigEndian.Uint16(addrData[8:10]),","sourceCodeStart":358,"sourceCodeEnd":394,"githubUrl":"https://github.com/nats-io/nats-server/blob/3a66a489d262bf89b71a71c955c94920394532f3/server/client_proxyproto.go#L358-L394","documentation":"During PROXY protocol v2 header parsing, the address family byte in the header was neither AF_INET (0x11), AF_INET6 (0x21), nor the UNSPEC (0x00) case handled earlier. The server rejects the connection because it cannot interpret the address payload that follows. The error is wrapped with errProxyProtoUnsupported so callers can test for the unsupported family class with errors.Is.","triggerScenarios":"A client connects through a PROXY-enabled listener and sends a v2 PROXY header whose address family/protocol byte (byte 14 of the header) is an undefined value, e.g. a corrupt or malicious header, or a sender claiming a protocol combination like UNIX stream (0x20/0x31) that this parser does not implement.","commonSituations":"Misconfigured load balancers emitting UNIX-socket or datagram family PROXY v2 headers; fuzzing or probes sending garbage after the 12-byte signature; protocol mismatches where a v1 header is misdetected as v2.","solutions":["Fix the upstream proxy/load balancer to emit a standard INET (0x11) or INET6 (0x21) v2 header, or disable PROXY protocol on the listener if the peer does not actually speak it.","If you need UNIX-socket family support, patch parseProxyProtoV2Header in server/client_proxyproto.go to handle that family, or pre-normalize headers at the proxy.","Catch the error with errors.Is(err, errProxyProtoUnsupported) and drop/close the connection rather than retrying, since the peer header is malformed."],"exampleFix":"// before: connection through lb fails\n// haproxy config sends raw v2 with unix family\n// after\ndefaults\n  mode tcp\n  option proxy-protocol-v2  # emit standard INET family\nserver s1 127.0.0.1:4222 send-proxy-v2","handlingStrategy":"fallback","validationCode":"if len(hdr) >= 15 && hdr[13] == 0x20 {\n    fam := hdr[14]\n    if fam != 0x00 && fam != 0x11 && fam != 0x21 {\n        return fmt.Errorf(\"pre-check: unsupported proxy v2 family 0x%02x\", fam)\n    }\n}","typeGuard":"func isSupportedV2Family(family byte) bool {\n    return family == 0x00 || family == 0x11 || family == 0x21\n}","tryCatchPattern":"addr, err := readProxyProtoHeader(conn)\nif errors.Is(err, errProxyProtoUnsupported) {\n    conn.Close() // malformed peer; do not retry\n    return\n} else if err != nil {\n    return err\n}","preventionTips":["Configure the load balancer to emit standard INET/INET6 v2 headers only","Do not enable PROXY protocol on listeners reached by non-PROXY clients","Log the raw family byte on failure to identify the offending proxy"],"tags":["proxy-protocol","network","protocol-parsing"],"backgroundTag":"proxy-protocol-unsupported-address-family","analyzedSha":"3a66a489d262bf89b71a71c955c94920394532f3","analyzedAt":"2026-09-02T04:41:54.247Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T15:18:49.778Z"}