{"record":{"id":"f5dcb101c39bd207","repo":"cilium/cilium","slug":"external-ipv4-node-address-could-not-be-derived-p","errorCode":null,"errorMessage":"external IPv4 node address could not be derived, please configure via --ipv4-node","messagePattern":"external IPv4 node address could not be derived, please configure via --ipv4-node","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/ipam/cell/ipam_init.go","lineNumber":263,"sourceCode":"\t\t\tr.logger.Debug(\n\t\t\t\tlogMessage,\n\t\t\t\tlogfields.V6Prefix, localNode.IPv6AllocCIDR,\n\t\t\t)\n\t\t}\n\t}\n}\n\n// ValidatePostInit validates the entire addressing setup and completes it as\n// required\nfunc (r *IPAMInitializer) ValidatePostInit(ctx context.Context) error {\n\tln, err := r.localNodeStore.Get(ctx)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to retrieve local node: %w\", err)\n\t}\n\n\tif r.daemonConfig.EnableIPv4 {\n\t\tif ln.GetNodeIP(false) == nil {\n\t\t\treturn fmt.Errorf(\"external IPv4 node address could not be derived, please configure via --ipv4-node\")\n\t\t}\n\t}\n\n\tif r.daemonConfig.TunnelingEnabled() && ln.GetNodeIP(false) == nil && ln.GetNodeIP(true) == nil {\n\t\treturn fmt.Errorf(\"external node address could not be derived, please configure via --ipv4-node or --ipv6-node\")\n\t}\n\n\tif r.daemonConfig.EnableIPv4 && ln.GetCiliumInternalIP(false) == nil {\n\t\treturn fmt.Errorf(\"BUG: Internal IPv4 node address was not configured\")\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":245,"sourceCodeEnd":277,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/ipam/cell/ipam_init.go#L245-L277","documentation":"ValidatePostInit could not derive an external IPv4 node address from the local node or system interfaces while IPv4 is enabled. Cilium needs a routable IPv4 address to identify the node; without it, IPAM validation fails. The error explicitly points to the --ipv4-node flag as the remedy.","triggerScenarios":"daemonConfig.EnableIPv4 is true and ln.GetNodeIP(false) returns nil — no external IPv4 address configured or auto-detected on the node.","commonSituations":"Running in containers/VMs without a global IPv4 address; Kubernetes nodes with only IPv6; missing or wrong --ipv4-node in dual-stack or IPv6-only clusters; auto-detection choosing an unusable interface.","solutions":["Set --ipv4-node=<routable-ipv4> explicitly on the agent","Verify the node has a usable external IPv4 address on a detected interface (check `ip addr`)","If the cluster is IPv6-only, disable IPv4 instead of leaving EnableIPv4 true","Check auto-detection configuration if an address exists but is being skipped"],"exampleFix":"// before\nargs := []string{\"cilium-agent\"}\n// after\nargs := []string{\"cilium-agent\", \"--ipv4-node=10.0.1.7\"}","handlingStrategy":"validation","validationCode":"// Go: check a routable IPv4 exists before starting with IPv4 enabled\naddrs, _ := net.InterfaceAddrs()\nhasGlobalV4 := false\nfor _, a := range addrs {\n    if ipnet, ok := a.(*net.IPNet); ok && ipnet.IP.To4() != nil && ipnet.IP.IsGlobalUnicast() {\n        hasGlobalV4 = true\n    }\n}\nif enableIPv4 && !hasGlobalV4 && ipv4NodeFlag == \"\" {\n    return errors.New(\"IPv4 enabled but no external IPv4 address; set --ipv4-node\")\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set --ipv4-node explicitly in address-less environments","Audit node interfaces before rollout","Disable IPv4 for IPv6-only clusters","Include node-IP derivation in preflight checks"],"tags":["ipam","ipv4","node-address","configuration"],"backgroundTag":"node-address-not-derivable","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}