{"record":{"id":"c014b55a116eb600","repo":"cilium/cilium","slug":"unable-to-replace-the-mtu-d-for-the-route-s-s","errorCode":null,"errorMessage":"unable to replace the mtu %d for the route %s: %s","messagePattern":"unable to replace the mtu (.+?) for the route (.+?): (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"plugins/cilium-cni/chaining/generic-veth/generic-veth.go","lineNumber":150,"sourceCode":"\t\t\tbreak\n\t\t}\n\n\t\tif !linkFound {\n\t\t\treturn errors.New(\"no link found inside container\")\n\t\t}\n\n\t\tif pluginCtx.NetConf.EnableRouteMTU || pluginCtx.CiliumConf.EnableRouteMTUForCNIChaining {\n\t\t\troutes, err := safenetlink.RouteList(nil, netlink.FAMILY_V4)\n\t\t\tif err != nil {\n\t\t\t\terr = fmt.Errorf(\"unable to list the IPv4 routes: %w\", err)\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tfor _, rt := range routes {\n\t\t\t\tif rt.MTU != int(pluginCtx.CiliumConf.RouteMTU) {\n\t\t\t\t\trt.MTU = int(pluginCtx.CiliumConf.RouteMTU)\n\t\t\t\t\terr = netlink.RouteReplace(&rt)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\terr = fmt.Errorf(\"unable to replace the mtu %d for the route %s: %s\", rt.MTU, rt.String(), err.Error())\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\n\t\t\troutes, err = safenetlink.RouteList(nil, netlink.FAMILY_V6)\n\t\t\tif err != nil {\n\t\t\t\terr = fmt.Errorf(\"unable to list the IPv6 routes: %w\", err)\n\t\t\t\treturn err\n\t\t\t}\n\t\t\tfor _, rt := range routes {\n\t\t\t\tif rt.MTU != int(pluginCtx.CiliumConf.RouteMTU) {\n\t\t\t\t\trt.MTU = int(pluginCtx.CiliumConf.RouteMTU)\n\t\t\t\t\terr = netlink.RouteReplace(&rt)\n\t\t\t\t\tif err != nil {\n\t\t\t\t\t\terr = fmt.Errorf(\"unable to replace the mtu %d for the route %s: %s\", rt.MTU, rt.String(), err.Error())\n\t\t\t\t\t\treturn err\n\t\t\t\t\t}","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/plugins/cilium-cni/chaining/generic-veth/generic-veth.go#L132-L168","documentation":"While iterating IPv4 routes in route-MTU mode, the plugin rewrites each route's MTU to Cilium's RouteMTU via netlink.RouteReplace. This error reports the target MTU, the route string, and the kernel's error message when the replacement fails. It means the pod's routing table could not be updated, which can break Cilium's egress/ingress datapath assumptions for the chained mode.","triggerScenarios":"netlink.RouteReplace(&rt) fails for a specific IPv4 route inside the container netns: e.g. EPERM (missing CAP_NET_ADMIN in the netns), the route was concurrently deleted, invalid MTU value, or the route is unreachable/locked by another manager.","commonSituations":"Container runtime dropping CAP_NET_ADMIN from the CNI plugin's netns context; conflicting MTU managers (both Cilium and a secondary CNI mutating MTU); RouteMTU set to 0 or an invalid value in the Cilium ConfigMap; route disappearing mid-loop due to concurrent networking changes.","solutions":["Read the %s kernel error in the message: EPERM → restore CAP_NET_ADMIN; ESRCH/ENETUNREACH → the route vanished (retry the pod).","Verify 'route-mtu' in the Cilium ConfigMap matches the underlying CNI's expectations (e.g. aws-cni's 9001).","Ensure only one component manages route MTU: disable enableRouteMTU if the primary CNI already sets MTU.","Retry pod creation; transient races usually resolve on retry."],"exampleFix":"// before (Cilium ConfigMap)\nenable-route-mtu: \"true\"\nroute-mtu: \"0\"\n// after\nenable-route-mtu: \"true\"\nroute-mtu: \"9001\"","handlingStrategy":"validation","validationCode":"// Validate before enabling route MTU patching\nif ciliumConf.RouteMTU < 68 || ciliumConf.RouteMTU > 65535 {\n    return fmt.Errorf(\"invalid route-mtu %d configured\", ciliumConf.RouteMTU)\n}","typeGuard":null,"tryCatchPattern":"err = netlink.RouteReplace(&rt)\nif err != nil {\n    switch {\n    case errors.Is(err, os.ErrPermission):\n        // missing CAP_NET_ADMIN in netns\n    case errors.Is(err, syscall.ESRCH):\n        // route removed concurrently — retry\n    }\n    return fmt.Errorf(\"unable to replace the mtu %d for the route %s: %s\", rt.MTU, rt.String(), err.Error())\n}","preventionTips":["Guarantee the CNI plugin retains CAP_NET_ADMIN in the container netns (don't strip caps in runtime config).","Have exactly one MTU manager: either the primary CNI or Cilium's enableRouteMTU, not both.","Set route-mtu to the value matching the underlying CNI (e.g. 9001 on AWS)."],"tags":["network","routes","mtu","cni"],"backgroundTag":"route-mtu-replace-failed","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}