cilium/cilium · error

native routing cidr must be configured with option --%s in c

Error message

native routing cidr must be configured with option --%s in combination with --%s=true --%s=true --%s=false --%s=%s

What it means

The IPv6 counterpart of the native-routing CIDR validation: when IPv6 masquerade is enabled in native routing mode, Cilium requires --ipv6-native-routing-cidr so the datapath can exclude in-cluster destinations from masquerade. Validation fails when it is unset under the RequiresNativeRouting conditions.

Source

Thrown at pkg/option/config.go:2998

		EnableIPMasqAgent,
		RoutingMode, RoutingModeNative,
		IPAM, c.IPAMMode())
}

func (c *DaemonConfig) checkIPv6NativeRoutingCIDR() error {
	if c.IPv6NativeRoutingCIDR.IsValid() {
		return nil
	}
	if !c.EnableIPv6 || !c.EnableIPv6Masquerade {
		return nil
	}
	if c.EnableIPMasqAgent {
		return nil
	}
	if !c.RequiresNativeRouting() {
		return nil
	}
	return fmt.Errorf(
		"native routing cidr must be configured with option --%s "+
			"in combination with --%s=true --%s=true --%s=false --%s=%s",
		IPv6NativeRoutingCIDR,
		EnableIPv6Name, EnableIPv6Masquerade,
		EnableIPMasqAgent,
		RoutingMode, RoutingModeNative)
}

func (c *DaemonConfig) checkIPAMDelegatedPlugin() error {
	if c.IPAM == ipamOption.IPAMDelegatedPlugin {
		// When using IPAM delegated plugin, IP addresses are allocated by the CNI binary,
		// not the daemon. Therefore, features which require the daemon to allocate IPs for itself
		// must be disabled.
		if c.EnableIPv4 && c.LocalRouterIPv4 == "" {
			return fmt.Errorf("--%s must be provided when IPv4 is enabled with --%s=%s", LocalRouterIPv4, IPAM, ipamOption.IPAMDelegatedPlugin)
		}
		if c.EnableIPv6 && c.LocalRouterIPv6 == "" {
			return fmt.Errorf("--%s must be provided when IPv6 is enabled with --%s=%s", LocalRouterIPv6, IPAM, ipamOption.IPAMDelegatedPlugin)

View on GitHub (pinned to ac7b90affa)

Solutions

1. Set --ipv6-native-routing-cidr=<IPv6 pod CIDR> matching the cluster's IPv6 pod CIDR
2. In Helm, set ipv6NativeRoutingCIDR in values
3. Set --routing-mode=tunnel if native routing is not intended
4. Or enable --enable-ip-masq-agent, which bypasses this requirement
5. If IPv6 is not used, disable it with --enable-ipv6=false

Example fix

# before
cilium-agent --enable-ipv6=true --routing-mode=native --enable-ipv6-masquerade=true
# after
cilium-agent --enable-ipv6=true --routing-mode=native --enable-ipv6-masquerade=true --ipv6-native-routing-cidr=fd00::/64

function validateNativeRoutingV6(cfg) {
  const nativeRequired = cfg.routingMode === 'native' && cfg.enableIPv6 && cfg.enableIPv6Masquerade && !cfg.enableIPMasqAgent;
  if (nativeRequired && !cfg.ipv6NativeRoutingCIDR) {
    throw new Error('ipv6-native-routing-cidr must be set in native routing mode with IPv6 masquerade');
  }
  return true;
}

function needsIPv6NativeCIDR(c) { return c.EnableIPv6 && c.EnableIPv6Masquerade && !c.EnableIPMasqAgent && c.RoutingMode === 'native'; }

When it happens

Trigger: DaemonConfig.Validate() runs with EnableIPv6=true, EnableIPv6Masquerade=true, EnableIPMasqAgent=false, RoutingMode=native, RequiresNativeRouting() true, and IPv6NativeRoutingCIDR empty — e.g. agent started with --enable-ipv6 --routing-mode=native but no --ipv6-native-routing-cidr.

Common situations: Dual-stack clusters switching to native routing mode without adding the IPv6 CIDR; Helm values updated for IPv6NativeRoutingCIDR missing; operators who set only the IPv4 CIDR.

Related errors

• native routing cidr must be configured with option --%s in c
• not ready
• no cilium agent pods found
• egress gateway requires an IPv4 underlay
• no local node v6 CIDR

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