{"record":{"id":"0f78f908ee8f110c","repo":"k3s-io/k3s","slug":"multiple-global-unicast-addresses-defined-for-s","errorCode":null,"errorMessage":"multiple global unicast addresses defined for %s, please set ip from one of %v","messagePattern":"multiple global unicast addresses defined for (.+?), please set ip from one of (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/util/net.go","lineNumber":302,"sourceCode":"\tfor _, addr := range addrs {\n\t\tip, _, err := net.ParseCIDR(addr.String())\n\t\tif err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"unable to parse CIDR for interface %s: %w\", iface.Name, err)\n\t\t}\n\t\t// if not IPv4 adding it on IPv6 list\n\t\tif ip.To4() == nil {\n\t\t\tif ip.IsGlobalUnicast() {\n\t\t\t\tglobalUnicastsIPv6 = append(globalUnicastsIPv6, ip.String())\n\t\t\t}\n\t\t\tcontinue\n\t\t}\n\t\tif ip.IsGlobalUnicast() {\n\t\t\tglobalUnicasts = append(globalUnicasts, ip.String())\n\t\t}\n\t}\n\n\tif len(globalUnicasts) > 1 {\n\t\treturn \"\", fmt.Errorf(\"multiple global unicast addresses defined for %s, please set ip from one of %v\", ifaceName, globalUnicasts)\n\t}\n\tif len(globalUnicasts) == 1 && len(globalUnicastsIPv6) == 0 {\n\t\treturn globalUnicasts[0], nil\n\t} else if len(globalUnicastsIPv6) > 0 && len(globalUnicasts) == 1 {\n\t\treturn globalUnicasts[0] + \",\" + globalUnicastsIPv6[0], nil\n\t} else if len(globalUnicastsIPv6) > 0 {\n\t\treturn globalUnicastsIPv6[0], nil\n\t}\n\n\treturn \"\", fmt.Errorf(\"can't find ip for interface %s\", ifaceName)\n}\n\ntype multiListener struct {\n\tlisteners []net.Listener\n\tclosing   chan struct{}\n\tconns     chan acceptRes\n}\n","sourceCodeStart":284,"sourceCodeEnd":320,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/util/net.go#L284-L320","documentation":"After collecting global unicast IPv4 and IPv6 addresses on the interface, if more than one IPv4 global unicast exists the function refuses to guess which one to use and lists the candidates in the error. This prevents silently binding the node/cluster to the wrong IP on multi-homed hosts.","triggerScenarios":"util.GetIPFromInterface on an interface with two or more public IPv4 addresses: secondary elastic IPs, floating IPs, IP aliases, or multi-homed NICs.","commonSituations":"Cloud nodes with extra EIPs (AWS) or floating IPs (Hetzner); load-balancer VIPs placed on the same NIC; addresses left by a CNI or metallb on the wrong interface; bare-metal hosts with multiple subnets on one interface.","solutions":["Pick one explicitly: set the node-ip (or equivalent bind-address) config to one of the candidates listed in the error","Remove the extra address from that interface if it is not needed","Point the interface option at a dedicated interface that has exactly one global unicast address"],"exampleFix":"# before\n--flannel-iface=eth0   # eth0 holds 10.0.0.5 and 192.0.2.7\n# after\n--node-ip=10.0.0.5","handlingStrategy":"validation","validationCode":"func countIPv4GlobalUnicasts(name string) ([]string, error) {\n\tiface, err := net.InterfaceByName(name)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\taddrs, _ := iface.Addrs()\n\tfound := []string{}\n\tfor _, a := range addrs {\n\t\tif ip, _, err := net.ParseCIDR(a.String()); err == nil && ip.To4() != nil && ip.IsGlobalUnicast() {\n\t\t\tfound = append(found, ip.String())\n\t\t}\n\t}\n\tif len(found) > 1 {\n\t\treturn nil, fmt.Errorf(\"ambiguous: %v - set node-ip explicitly\", found)\n\t}\n\treturn found, nil\n}","typeGuard":null,"tryCatchPattern":"ip, err := util.GetIPFromInterface(cfg.Iface)\nif err != nil && strings.Contains(err.Error(), \"multiple global unicast addresses\") {\n\t// candidates are listed in the error; require an explicit node-ip in config\n\treturn \"\", fmt.Errorf(\"%w: set --node-ip explicitly\", err)\n}","preventionTips":["Always set node-ip explicitly on hosts that carry floating/secondary IPs","Keep cluster traffic off interfaces that host VIPs or LB addresses","Audit ip addr show before adding elastic/floating IPs to a cluster node"],"tags":["go","network","interface","multi-homed","configuration"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}