{"record":{"id":"07d9be0ae216b661","repo":"v2rayA/v2rayA","slug":"no-suitable-ipv4-address-found","errorCode":null,"errorMessage":"no suitable IPv4 address found","messagePattern":"no suitable IPv4 address found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"service/kernel/v2ray/template_inbound.go","lineNumber":105,"sourceCode":"\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t} else {\n\t\t\t\tif ip.To4() != nil {\n\t\t\t\t\t// IPv4 address\n\t\t\t\t\treturn ip, nil\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tif bestIP != nil {\n\t\treturn bestIP, nil\n\t}\n\n\tif preferIPv6 {\n\t\treturn nil, errors.New(\"no suitable IPv6 address found\")\n\t}\n\treturn nil, errors.New(\"no suitable IPv4 address found\")\n}\n\n// GetLinkLocalIPv6 returns a link-local IPv6 address as fallback\nfunc GetLinkLocalIPv6() (net.IP, error) {\n\tinterfaces, err := net.Interfaces()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tfor _, iface := range interfaces {\n\t\tif iface.Flags&net.FlagUp == 0 {\n\t\t\tcontinue\n\t\t}\n\n\t\t// Skip TUN interfaces\n\t\tifName := strings.ToLower(iface.Name)\n\t\tif strings.Contains(ifName, \"tun\") || strings.Contains(ifName, \"tap\") {\n\t\t\tcontinue","sourceCodeStart":87,"sourceCodeEnd":123,"githubUrl":"https://github.com/v2rayA/v2rayA/blob/71e5442fc548c05680ee55eae943e6c0afe9ac51/service/kernel/v2ray/template_inbound.go#L87-L123","documentation":"The IPv4 branch of GetBestLocalIP: when preferIPv6 is false and no suitable IPv4 address was found on any interface, it returns \"no suitable IPv4 address found\". It complements the IPv6 error and surfaces when the host genuinely lacks a usable IPv4 unicast address for binding.","triggerScenarios":"Calling GetBestLocalIP with preferIPv6=false on a host with no non-loopback (per filter) IPv4 address — e.g. IPv6-only environment or interfaces down.","commonSituations":"IPv6-only containers/VPS; all interfaces except loopback down; unusual filtering that excludes the host's IPv4 addresses; misconfigured sendThrough preference on an IPv6-only box.","solutions":["Switch the preference to IPv6 (preferIPv6=true) if the host is IPv6-only.","Bring up an interface with an IPv4 address or assign one (ip addr add / DHCP).","Review the filter logic in GetBestLocalIP to confirm the existing IPv4 address isn't wrongly excluded.","Provide an explicit sendThrough address in the config instead of auto-selection."],"exampleFix":"// before\nip, err := GetBestLocalIP(false) // IPv4-only preference on IPv6-only host\n\n// after\nip, err := GetBestLocalIP(true) // use IPv6 when no IPv4 is available","handlingStrategy":"fallback","validationCode":"hasV4 := false\naddrs, _ := net.InterfaceAddrs()\nfor _, a := range addrs {\n    if ipn, ok := a.(*net.IPNet); ok && ipn.IP.To4() != nil && ipn.IP.IsGlobalUnicast() {\n        hasV4 = true\n    }\n}\nif !hasV4 { preferIPv6 = true }","typeGuard":"func hostHasIPv4() bool {\n    addrs, err := net.InterfaceAddrs()\n    if err != nil { return false }\n    for _, a := range addrs {\n        if ipn, ok := a.(*net.IPNet); ok && ipn.IP.To4() != nil && ipn.IP.IsGlobalUnicast() { return true }\n    }\n    return false\n}","tryCatchPattern":"ip, err := GetBestLocalIP(false)\nif err != nil {\n    ip, err = GetBestLocalIP(true)\n    if err != nil { return fmt.Errorf(\"no usable bind address: %w\", err) }\n}","preventionTips":["Ensure at least one interface has an IPv4 address before enabling the service.","On IPv6-only hosts, prefer IPv6 selection or set sendThrough explicitly.","Check interface state (not just addresses) when diagnosing."],"tags":["network","ipv4","address-selection"],"backgroundTag":"no-ipv4-address","analyzedSha":"71e5442fc548c05680ee55eae943e6c0afe9ac51","analyzedAt":"2026-09-05T20:04:37.459Z","contentChangedAt":"2026-09-05T20:04:37.459Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}