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 --%s=%s

What it means

Cilium requires an explicit native routing CIDR (--ipv4-native-routing-cidr) whenever IPv4 masquerade is enabled under native routing mode, except in ENI/AlibabaCloud IPAM modes where it is unnecessary. Without it, the datapath cannot decide which destinations must not be masqueraded, so IPv4 daemon validation fails.

Source

Thrown at pkg/option/config.go:2975

func (c *DaemonConfig) checkIPv4NativeRoutingCIDR() error {
	if c.IPv4NativeRoutingCIDR.IsValid() {
		return nil
	}
	if !c.EnableIPv4 || !c.EnableIPv4Masquerade {
		return nil
	}
	if c.EnableIPMasqAgent {
		return nil
	}
	if !c.RequiresNativeRouting() {
		return nil
	}
	if c.IPAMMode() == ipamOption.IPAMENI || c.IPAMMode() == ipamOption.IPAMAlibabaCloud {
		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 --%s=%s",
		IPv4NativeRoutingCIDR,
		EnableIPv4Name, EnableIPv4Masquerade,
		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

View on GitHub (pinned to ac7b90affa)

Solutions

1. Set --ipv4-native-routing-cidr=<pod CIDR> (e.g. 10.0.0.0/8) matching the cluster pod CIDR
2. In Helm, set ipv4NativeRoutingCIDR in values
3. Alternatively set --routing-mode=tunnel if native routing is not actually required
4. If using ENI or AlibabaCloud IPAM, this check is skipped — verify the IPAM mode is what you intend
5. Or enable the IP masquerade agent (--enable-ip-masq-agent) which changes the validation path

Example fix

# before
cilium-agent --routing-mode=native --enable-ipv4-masquerade=true
# after
cilium-agent --routing-mode=native --enable-ipv4-masquerade=true --ipv4-native-routing-cidr=10.0.0.0/8

function validateNativeRoutingV4(cfg) {
  const nativeRequired = cfg.routingMode === 'native' && cfg.enableIPv4 && cfg.enableIPv4Masquerade && !cfg.enableIPMasqAgent;
  const ipamExempt = ['eni', 'alibabacloud'].includes(cfg.ipamMode);
  if (nativeRequired && !ipamExempt && !cfg.ipv4NativeRoutingCIDR) {
    throw new Error('ipv4-native-routing-cidr must be set in native routing mode with IPv4 masquerade');
  }
  return true;
}

function needsIPv4NativeCIDR(c) { return c.EnableIPv4 && c.EnableIPv4Masquerade && !c.EnableIPMasqAgent && c.RoutingMode === 'native'; }

When it happens

Trigger: DaemonConfig.Validate() reaches the IPv4NativeRoutingCIDR check (validateConfigVIPOrDefault path) when: IPv4NativeRoutingCIDR is empty, IPAM mode is not ENI/AlibabaCloud, EnableIPv4=true, EnableIPv4Masquerade=true, EnableIPMasqAgent=false, and RoutingMode is native (RoutingModeNative) — i.e. the RequiresNativeRouting conditions hold.

Common situations: Running with --routing-mode=native (or tunneling disabled) without setting --ipv4-native-routing-cidr; switching from tunnel to native mode in Helm values and forgetting the CIDR; kube-proxy-replacement native-routing deployments.

Related errors

• BPF masquerade requires (--%s="true" or --%s="true")
• egress gateway requires --%s="true" and --%s="true"
• native routing cidr must be configured with option --%s in c
• not ready
• no cilium agent pods found

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