{"record":{"id":"565af4b997784410","repo":"k3s-io/k3s","slug":"no-ipv4-address-found","errorCode":null,"errorMessage":"no IPv4 address found","messagePattern":"no IPv4 address found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/util/net.go","lineNumber":56,"sourceCode":"\tfor _, elem := range elems {\n\t\tif elem == nil || elem.IP.To4() == nil {\n\t\t\tcontinue\n\t\t}\n\t\treturn elem, nil\n\t}\n\treturn nil, errors.New(\"no IPv4 CIDRs found\")\n}\n\n// getFirst4 returns the first IPv4 address from the list of IP addresses.\n// If no IPv4 addresses are found, an error is raised.\nfunc getFirst4(elems []net.IP) (net.IP, error) {\n\tfor _, elem := range elems {\n\t\tif elem == nil || elem.To4() == nil {\n\t\t\tcontinue\n\t\t}\n\t\treturn elem, nil\n\t}\n\treturn nil, errors.New(\"no IPv4 address found\")\n}\n\n// GetFirst4String returns the first IPv4 address from a list of IP address strings.\n// If no IPv4 addresses are found, an error is raised.\nfunc GetFirst4String(elems []string) (string, error) {\n\tips := []net.IP{}\n\tfor _, elem := range elems {\n\t\tfor _, v := range strings.Split(elem, \",\") {\n\t\t\tips = append(ips, net.ParseIP(v))\n\t\t}\n\t}\n\tip, err := getFirst4(ips)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\treturn ip.String(), nil\n}\n","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/util/net.go#L38-L74","documentation":"getFirst4Net's sibling getFirst4 in pkg/util/net.go returns the first IPv4 net.IP from a list, or 'no IPv4 address found' when all entries are nil or IPv6. It backs the exported GetFirst4String, used to pick an IPv4 address from settings like --node-ip, advertise addresses, or bind addresses.","triggerScenarios":"Passing an address list with only IPv6 entries to a code path that requires IPv4 - e.g. --node-ip set to a single v6 address on a component that derives an IPv4 service/bind address from it, or GetFirstString called where no v4 fallback is tolerated.","commonSituations":"IPv6-only hosts; --node-ip typo'd or partially set; interfaces lacking IPv4 during network reconfiguration; dual-stack flags missing their v4 member.","solutions":["Include an IPv4 in the address list: --node-ip=192.0.2.10,2001:db8::10 (or set the IPv4 on the interface used for autodetection).","Ensure the node's primary interface has a global unicast IPv4 address when autodetection is used.","If the node is intentionally IPv6-only, use GetFirstString (v4-then-v6 fallback) or the v6-specific helpers instead of IPv4-requiring paths."],"exampleFix":"# before: v6-only node-ip, IPv4 derivation fails\nk3s server --node-ip=2001:db8::10\n\n# after: dual-stack node-ip\nk3s server --node-ip=192.0.2.10,2001:db8::10","handlingStrategy":"validation","validationCode":"// Equivalent of GetFirst4String pre-check\ncount := 0\nfor _, s := range strings.Split(nodeIPFlag, \",\") {\n    if ip := net.ParseIP(s); ip != nil && ip.To4() != nil {\n        count++\n    }\n}\nif count == 0 {\n    return errors.New(\"no IPv4 in node-ip list\")\n}","typeGuard":null,"tryCatchPattern":"if err != nil && strings.Contains(err.Error(), \"no IPv4 address found\") {\n    // add an IPv4 to --node-ip or fix the interface, then restart\n}","preventionTips":["Set --node-ip with both families on dual-stack nodes.","Ensure autodetected interfaces hold a global unicast IPv4.","Use GetFirstString when a v6 fallback is acceptable instead of v4-only helpers."],"tags":["k3s","network","ipv4","node-ip","configuration","dual-stack"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}