{"record":{"id":"03624b9c434f5163","repo":"k3s-io/k3s","slug":"interface-s-does-not-have-a-correct-global-unicas","errorCode":null,"errorMessage":"interface %s does not have a correct global unicast ip: %w","messagePattern":"interface (.+?) does not have a correct global unicast ip: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/util/net.go","lineNumber":262,"sourceCode":"\treturn cidr, err\n}\n\n// IPStringToIPNet converts an IP string to an IPNet, using a fully filled mask appropriate for the address family.\nfunc IPStringToIPNet(address string) (*net.IPNet, error) {\n\tif strings.Contains(address, \":\") {\n\t\taddress += \"/128\"\n\t} else {\n\t\taddress += \"/32\"\n\t}\n\t_, cidr, err := net.ParseCIDR(address)\n\treturn cidr, err\n}\n\n// GetIPFromInterface is the public function that returns the IP of an interface\nfunc GetIPFromInterface(ifaceName string) (string, error) {\n\tip, err := getIPFromInterface(ifaceName)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"interface %s does not have a correct global unicast ip: %w\", ifaceName, err)\n\t}\n\tlogrus.Infof(\"Found ip %s from iface %s\", ip, ifaceName)\n\treturn ip, nil\n}\n\n// getIPFromInterface is the private function that returns de IP of an interface\nfunc getIPFromInterface(ifaceName string) (string, error) {\n\tiface, err := net.InterfaceByName(ifaceName)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\taddrs, err := iface.Addrs()\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\tif iface.Flags&net.FlagUp == 0 {\n\t\treturn \"\", fmt.Errorf(\"the interface %s is not up\", ifaceName)\n\t}","sourceCodeStart":244,"sourceCodeEnd":280,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/util/net.go#L244-L280","documentation":"GetIPFromInterface wraps any failure of the private getIPFromInterface: interface not found, failure reading its addresses, interface down, an unparseable CIDR, or no global unicast address at all. The wrapper names the interface so you can tell which configured interface name (e.g. a flannel-iface/node-iface style option) failed.","triggerScenarios":"Calling util.GetIPFromInterface(\"eth1\") when eth1 does not exist, exists but is DOWN, has only link-local/loopback addresses, or reports an address the code cannot re-parse as CIDR.","commonSituations":"Misconfigured interface name ('eth0' on a host using 'ens192'/'enp0s2' predictable names); VMs/cloud images with renamed NICs; addresses arriving late via DHCP so the interface is empty at startup; containers where the expected host interface is not visible.","solutions":["Confirm the interface exists: ip link show <iface>; if missing, find the real name with ip -o link and fix the config","If present but unconfigured, assign an address (DHCP or static) and retry - the code requires the interface up with a global unicast address","On multi-NIC hosts, pin the interface or node-ip explicitly instead of relying on auto-detection","Re-run and read the wrapped message - it distinguishes not-found vs down vs no-address cases"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"func InterfaceHasGlobalUnicast(name string) error {\n\tiface, err := net.InterfaceByName(name)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"interface %s not found: %w\", name, err)\n\t}\n\tif iface.Flags&net.FlagUp == 0 {\n\t\treturn fmt.Errorf(\"interface %s is down\", name)\n\t}\n\taddrs, err := iface.Addrs()\n\tif err != nil {\n\t\treturn err\n\t}\n\tfor _, a := range addrs {\n\t\tif ip, _, err := net.ParseCIDR(a.String()); err == nil && ip.IsGlobalUnicast() {\n\t\t\treturn nil\n\t\t}\n\t}\n\treturn fmt.Errorf(\"interface %s has no global unicast address\", name)\n}","typeGuard":null,"tryCatchPattern":"ip, err := util.GetIPFromInterface(cfg.Iface)\nif err != nil {\n\tif strings.Contains(err.Error(), \"does not have a correct global unicast ip\") {\n\t\t// check existence, link state, and ip addr show <iface> on this host\n\t}\n\treturn \"\", err\n}","preventionTips":["Pin the interface name explicitly in config on multi-NIC hosts","Verify with ip link show and ip addr show before starting services that derive their IP","Expect predictable NIC names (ens*, enp*) on modern distros - do not assume eth0","Add startup readiness checks that wait for the interface to have a global unicast address"],"tags":["go","network","interface","configuration","nic"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}