{"record":{"id":"bcbeb42c10d1ad53","repo":"slackhq/nebula","slug":"errinvalidipv6remoteforsocket","errorCode":"ErrInvalidIPv6RemoteForSocket","errorMessage":"listener is IPv4, but writing to IPv6 remote","messagePattern":"listener is IPv4, but writing to IPv6 remote","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"udp/errors.go","lineNumber":5,"sourceCode":"package udp\n\nimport \"errors\"\n\nvar ErrInvalidIPv6RemoteForSocket = errors.New(\"listener is IPv4, but writing to IPv6 remote\")\n","sourceCodeStart":1,"sourceCodeEnd":6,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/udp/errors.go#L1-L6","documentation":"ErrInvalidIPv6RemoteForSocket is nebula's udp package sentinel returned by WriteTo and writeSockaddr when the UDP socket was bound IPv4-only (u.isV4) but the caller attempts to send to an IPv6 address. The underlying sockaddr construction cannot represent an IPv6 destination on an AF_INET socket, so the write is refused up front.","triggerScenarios":"Calling udpConn.WriteTo (or the internal writeSockaddr path on darwin udp/udp_darwin.go:98 and linux udp/udp_linux.go:375) with an addr whose ip.Is6() is true while the listener was created with an IPv4-only bind address (e.g. 0.0.0.0 or a specific v4 address).","commonSituations":"Dual-stack misconfiguration: cert/config advertises or resolves an IPv6 nebula addr while the listener is bound to an IPv4 address; DNS resolving a hostname to an AAAA record for the remote; firewall/NAT environment forcing v4 bind but peer discovered via v6.","solutions":["Bind the listener dual-stack or to an IPv6 address (::) if IPv6 peers must be reached","Remove/avoid IPv6 addresses in nebula's config (preferred_addresses/ranges) when the host has no IPv6 connectivity","Force remote resolution to A records (IPv4) so WriteTo never receives a v6 address","Check that udp_hostaddr/preferred ranges in config match the socket family actually bound"],"exampleFix":"// before (v4-only bind, v6 remote possible)\nudpConns, err := udp.NewListener(l, \"0.0.0.0\", port, true, 2)\n// after (dual-stack bind)\nudpConns, err := udp.NewListener(l, \"::\", port, true, 2)","handlingStrategy":"validation","validationCode":"remote, err := netip.ParseAddr(remoteStr)\nif err != nil {\n    return err\n}\nif listenerIsV4 && remote.Is6() {\n    return fmt.Errorf(\"cannot send to %s via IPv4-only socket\", remote)\n}","typeGuard":"func canSendFromV4(remote netip.Addr) bool { return !remote.Is6() }","tryCatchPattern":"err := udpConn.WriteTo(b, remote)\nif errors.Is(err, udp.ErrInvalidIPv6RemoteForSocket) {\n    l.WithField(\"remote\", remote).Warn(\"dropping packet: v4 socket, v6 remote\")\n    return\n}","preventionTips":["Match listener bind family to the set of remote addresses configured","Avoid AAAA-only DNS names for peers when binding IPv4","On v4-only hosts, strip IPv6 from preferred_addresses/ranges","Prefer dual-stack (::) binds when both address families are in play"],"tags":["nebula","udp","ipv6","socket","network"],"backgroundTag":"address-family-mismatch","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}