{"record":{"id":"3e7efcda2c03bc7a","repo":"cilium/cilium","slug":"external-ipv6-address-unavailable","errorCode":null,"errorMessage":"external IPv6 address unavailable","messagePattern":"external IPv6 address unavailable","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/linux/node.go","lineNumber":373,"sourceCode":"\tvar (\n\t\tlocal   net.IP\n\t\tnexthop *net.IP\n\t\tmtu     int\n\t)\n\tif prefix.Addr().Is4() {\n\t\tif !n.nodeConfig.CiliumInternalIPv4.IsValid() {\n\t\t\treturn route.Route{}, fmt.Errorf(\"IPv4 router address unavailable\")\n\t\t}\n\n\t\tlocal = net.IP(n.nodeConfig.CiliumInternalIPv4.AsSlice())\n\t\tnexthop = &local\n\t} else {\n\t\tif !n.nodeConfig.CiliumInternalIPv6.IsValid() {\n\t\t\treturn route.Route{}, fmt.Errorf(\"IPv6 router address unavailable\")\n\t\t}\n\n\t\tif !n.nodeConfig.NodeIPv6.IsValid() {\n\t\t\treturn route.Route{}, fmt.Errorf(\"external IPv6 address unavailable\")\n\t\t}\n\n\t\t// For ipv6, kernel will reject \"ip r a $cidr via $ipv6_cilium_host dev cilium_host\"\n\t\t// with \"Error: Gateway can not be a local address\". Instead, we have to remove \"via\"\n\t\t// as \"ip r a $cidr dev cilium_host\" to make it work.\n\t\tnexthop = nil\n\t\tlocal = net.IP(n.nodeConfig.CiliumInternalIPv6.AsSlice())\n\t}\n\n\tif !isLocalNode {\n\t\tmtu = n.nodeConfig.RouteMTU\n\t}\n\n\t// The default routing table accounts for encryption overhead for encrypt-node traffic\n\treturn route.Route{\n\t\tNexthop:  nexthop,\n\t\tLocal:    local,\n\t\tDevice:   n.datapathConfig.HostDevice,","sourceCodeStart":355,"sourceCodeEnd":391,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/linux/node.go#L355-L391","documentation":"This error comes from createNodeRouteSpec in the Cilium Linux datapath node handler. When building an IPv6 node route (a route pointing a pod CIDR at the cilium_host device), the handler requires the node's external IPv6 address (NodeIPv6) to be set; if it is the zero/invalid value, no valid route spec can be constructed. It is a configuration-completeness guard: the node object did not carry an IPv6 node address even though IPv6 routes are being programmed.","triggerScenarios":"Any of lookupNodeRoute, updateNodeRoute or deleteNodeRoute for an IPv6 prefix (via updateOrRemoveNodeRoutes) when n.nodeConfig.NodeIPv6 is invalid — i.e. the local node has no external IPv6 address while EnableIPv6 is on and pod IPv6 CIDRs need routing.","commonSituations":"Clusters/nodes without IPv6 connectivity (no IPv6 address on the node) while Cilium IPv6 is enabled; kubelet not reporting an IPv6 address for the node; misconfigured bootstrap where NodeIPv6 was never populated before local route restoration.","solutions":["Ensure the node has a global IPv6 address and that it is advertised to the Kubernetes API (node.spec.addresses), then restart the Cilium agent","If the cluster is IPv4-only, disable IPv6 in Cilium (enable-ipv6=false) so no IPv6 node routes are programmed","Check node_config bootstrap: verify cilium nodeconfig / local node store populated CiliumInternalIPv6 and NodeIPv6 before the datapath initializes","Inspect `cilium status` and agent logs for earlier errors indicating the local node's IPv6 could not be discovered"],"exampleFix":"// before: IPv6 enabled on an IPv4-only node\nenable-ipv6=true\n// after\nenable-ipv6=false   # or provision a global IPv6 address on the node","handlingStrategy":"validation","validationCode":"if cfg.NodeIPv6.IsValid() {\n    // safe to program IPv6 node routes\n} else {\n    logger.Warn(\"skipping IPv6 node routes: no external IPv6 address\")\n}","typeGuard":"func hasNodeIPv6(cfg NodeConfig) bool { return cfg.NodeIPv6.IsValid() }","tryCatchPattern":"if err := handler.NodeUpdate(old, new); err != nil {\n    if strings.Contains(err.Error(), \"external IPv6 address unavailable\") {\n        logger.Warn(\"IPv6 node address missing; IPv6 datapath disabled\", \"err\", err)\n    } else {\n        return err\n    }\n}","preventionTips":["Only enable IPv6 in Cilium when nodes have global IPv6 addresses","Verify node addressing is populated before datapath initialization","Monitor node objects for missing IPv6 addresses in dual-stack clusters"],"tags":["network","ipv6","routing","cilium-datapath"],"backgroundTag":"missing-node-ipv6-address","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}