external IPv4 node address could not be derived, please conf

Error message

external IPv4 node address could not be derived, please configure via --ipv4-node

What it means

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.

Source

Thrown at pkg/ipam/cell/ipam_init.go:263

			r.logger.Debug(
				logMessage,
				logfields.V6Prefix, localNode.IPv6AllocCIDR,
			)
		}
	}
}

// ValidatePostInit validates the entire addressing setup and completes it as
// required
func (r *IPAMInitializer) ValidatePostInit(ctx context.Context) error {
	ln, err := r.localNodeStore.Get(ctx)
	if err != nil {
		return fmt.Errorf("failed to retrieve local node: %w", err)
	}

	if r.daemonConfig.EnableIPv4 {
		if ln.GetNodeIP(false) == nil {
			return fmt.Errorf("external IPv4 node address could not be derived, please configure via --ipv4-node")
		}
	}

	if r.daemonConfig.TunnelingEnabled() && ln.GetNodeIP(false) == nil && ln.GetNodeIP(true) == nil {
		return fmt.Errorf("external node address could not be derived, please configure via --ipv4-node or --ipv6-node")
	}

	if r.daemonConfig.EnableIPv4 && ln.GetCiliumInternalIP(false) == nil {
		return fmt.Errorf("BUG: Internal IPv4 node address was not configured")
	}

	return nil
}

View on GitHub (pinned to ac7b90affa)

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

Example fix

// before
args := []string{"cilium-agent"}
// after
args := []string{"cilium-agent", "--ipv4-node=10.0.1.7"}

Defensive patterns

Strategy: validation

Validate before calling

// Go: check a routable IPv4 exists before starting with IPv4 enabled
addrs, _ := net.InterfaceAddrs()
hasGlobalV4 := false
for _, a := range addrs {
    if ipnet, ok := a.(*net.IPNet); ok && ipnet.IP.To4() != nil && ipnet.IP.IsGlobalUnicast() {
        hasGlobalV4 = true
    }
}
if enableIPv4 && !hasGlobalV4 && ipv4NodeFlag == "" {
    return errors.New("IPv4 enabled but no external IPv4 address; set --ipv4-node")
}

Prevention

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

When it happens

Trigger: daemonConfig.EnableIPv4 is true and ln.GetNodeIP(false) returns nil — no external IPv4 address configured or auto-detected on the node.

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

Related errors

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