cilium/cilium · error

external IPv6 address unavailable

Error message

external IPv6 address unavailable

What it means

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.

Source

Thrown at pkg/datapath/linux/node.go:373

	var (
		local   net.IP
		nexthop *net.IP
		mtu     int
	)
	if prefix.Addr().Is4() {
		if !n.nodeConfig.CiliumInternalIPv4.IsValid() {
			return route.Route{}, fmt.Errorf("IPv4 router address unavailable")
		}

		local = net.IP(n.nodeConfig.CiliumInternalIPv4.AsSlice())
		nexthop = &local
	} else {
		if !n.nodeConfig.CiliumInternalIPv6.IsValid() {
			return route.Route{}, fmt.Errorf("IPv6 router address unavailable")
		}

		if !n.nodeConfig.NodeIPv6.IsValid() {
			return route.Route{}, fmt.Errorf("external IPv6 address unavailable")
		}

		// For ipv6, kernel will reject "ip r a $cidr via $ipv6_cilium_host dev cilium_host"
		// with "Error: Gateway can not be a local address". Instead, we have to remove "via"
		// as "ip r a $cidr dev cilium_host" to make it work.
		nexthop = nil
		local = net.IP(n.nodeConfig.CiliumInternalIPv6.AsSlice())
	}

	if !isLocalNode {
		mtu = n.nodeConfig.RouteMTU
	}

	// The default routing table accounts for encryption overhead for encrypt-node traffic
	return route.Route{
		Nexthop:  nexthop,
		Local:    local,
		Device:   n.datapathConfig.HostDevice,

View on GitHub (pinned to ac7b90affa)

Solutions

1. 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
2. If the cluster is IPv4-only, disable IPv6 in Cilium (enable-ipv6=false) so no IPv6 node routes are programmed
3. Check node_config bootstrap: verify cilium nodeconfig / local node store populated CiliumInternalIPv6 and NodeIPv6 before the datapath initializes
4. Inspect `cilium status` and agent logs for earlier errors indicating the local node's IPv6 could not be discovered

Example fix

// before: IPv6 enabled on an IPv4-only node
enable-ipv6=true
// after
enable-ipv6=false   # or provision a global IPv6 address on the node

if cfg.NodeIPv6.IsValid() {
    // safe to program IPv6 node routes
} else {
    logger.Warn("skipping IPv6 node routes: no external IPv6 address")
}

func hasNodeIPv6(cfg NodeConfig) bool { return cfg.NodeIPv6.IsValid() }

if err := handler.NodeUpdate(old, new); err != nil {
    if strings.Contains(err.Error(), "external IPv6 address unavailable") {
        logger.Warn("IPv6 node address missing; IPv6 datapath disabled", "err", err)
    } else {
        return err
    }
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• failed to enable local node route: update ipv6 routes: %w
• failed to add aux route %q: %w
• failed to remove aux route %q: %w
• failed to enable local node route: update ipv4 routes: %w
• failed to enable direct routes for ipv6: %w

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/3e7efcda2c03bc7a. Report an issue: GitHub.