{"record":{"id":"1008dbbcad7a7243","repo":"cilium/cilium","slug":"native-routing-cidr-must-be-configured-with-option","errorCode":null,"errorMessage":"native routing cidr must be configured with option --%s in combination with --%s=true --%s=true --%s=false --%s=%s --%s=%s","messagePattern":"native routing cidr must be configured with option --(.+?) in combination with --(.+?)=true --(.+?)=true --(.+?)=false --(.+?)=(.+?) --(.+?)=(.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/option/config.go","lineNumber":2975,"sourceCode":"\nfunc (c *DaemonConfig) checkIPv4NativeRoutingCIDR() error {\n\tif c.IPv4NativeRoutingCIDR.IsValid() {\n\t\treturn nil\n\t}\n\tif !c.EnableIPv4 || !c.EnableIPv4Masquerade {\n\t\treturn nil\n\t}\n\tif c.EnableIPMasqAgent {\n\t\treturn nil\n\t}\n\tif !c.RequiresNativeRouting() {\n\t\treturn nil\n\t}\n\tif c.IPAMMode() == ipamOption.IPAMENI || c.IPAMMode() == ipamOption.IPAMAlibabaCloud {\n\t\treturn nil\n\t}\n\n\treturn fmt.Errorf(\n\t\t\"native routing cidr must be configured with option --%s \"+\n\t\t\t\"in combination with --%s=true --%s=true --%s=false --%s=%s --%s=%s\",\n\t\tIPv4NativeRoutingCIDR,\n\t\tEnableIPv4Name, EnableIPv4Masquerade,\n\t\tEnableIPMasqAgent,\n\t\tRoutingMode, RoutingModeNative,\n\t\tIPAM, c.IPAMMode())\n}\n\nfunc (c *DaemonConfig) checkIPv6NativeRoutingCIDR() error {\n\tif c.IPv6NativeRoutingCIDR.IsValid() {\n\t\treturn nil\n\t}\n\tif !c.EnableIPv6 || !c.EnableIPv6Masquerade {\n\t\treturn nil\n\t}\n\tif c.EnableIPMasqAgent {\n\t\treturn nil","sourceCodeStart":2957,"sourceCodeEnd":2993,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/option/config.go#L2957-L2993","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --ipv4-native-routing-cidr=<pod CIDR> (e.g. 10.0.0.0/8) matching the cluster pod CIDR","In Helm, set ipv4NativeRoutingCIDR in values","Alternatively set --routing-mode=tunnel if native routing is not actually required","If using ENI or AlibabaCloud IPAM, this check is skipped — verify the IPAM mode is what you intend","Or enable the IP masquerade agent (--enable-ip-masq-agent) which changes the validation path"],"exampleFix":"# before\ncilium-agent --routing-mode=native --enable-ipv4-masquerade=true\n# after\ncilium-agent --routing-mode=native --enable-ipv4-masquerade=true --ipv4-native-routing-cidr=10.0.0.0/8","handlingStrategy":"validation","validationCode":"function validateNativeRoutingV4(cfg) {\n  const nativeRequired = cfg.routingMode === 'native' && cfg.enableIPv4 && cfg.enableIPv4Masquerade && !cfg.enableIPMasqAgent;\n  const ipamExempt = ['eni', 'alibabacloud'].includes(cfg.ipamMode);\n  if (nativeRequired && !ipamExempt && !cfg.ipv4NativeRoutingCIDR) {\n    throw new Error('ipv4-native-routing-cidr must be set in native routing mode with IPv4 masquerade');\n  }\n  return true;\n}","typeGuard":"function needsIPv4NativeCIDR(c) { return c.EnableIPv4 && c.EnableIPv4Masquerade && !c.EnableIPMasqAgent && c.RoutingMode === 'native'; }","tryCatchPattern":null,"preventionTips":["Always pair --routing-mode=native with --ipv4-native-routing-cidr set to the cluster pod CIDR","Set ipv4NativeRoutingCIDR in Helm values when tunnel.enabled=false","Remember ENI/AlibabaCloud IPAM modes are exempt; verify ipamMode when toggling native routing","Add a pre-deploy lint that checks native-routing flags as a set"],"tags":["cilium","networking","masquerade","configuration"],"backgroundTag":"missing-required-config-option","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}