{"record":{"id":"83b97c44302705c6","repo":"slackhq/nebula","slug":"failed-to-set-mtu-v-on-the-default-route-v-v","errorCode":null,"errorMessage":"failed to set mtu %v on the default route %v; %v","messagePattern":"failed to set mtu (.+?) on the default route (.+?); (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"overlay/tun_linux.go","lineNumber":565,"sourceCode":"\terr := netlink.RouteReplace(&nr)\n\tif err != nil {\n\t\tt.l.Warn(\"Failed to set default route MTU, retrying\", \"error\", err, \"cidr\", cidr)\n\t\t//retry twice more -- on some systems there appears to be a race condition where if we set routes too soon, netlink says `invalid argument`\n\t\tfor i := 0; i < 2; i++ {\n\t\t\ttime.Sleep(100 * time.Millisecond)\n\t\t\terr = netlink.RouteReplace(&nr)\n\t\t\tif err == nil {\n\t\t\t\tbreak\n\t\t\t} else {\n\t\t\t\tt.l.Warn(\"Failed to set default route MTU, retrying\",\n\t\t\t\t\t\"error\", err,\n\t\t\t\t\t\"cidr\", cidr,\n\t\t\t\t\t\"mtu\", t.DefaultMTU,\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"failed to set mtu %v on the default route %v; %v\", t.DefaultMTU, dr, err)\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (t *tun) addRoutes(logErrors bool) error {\n\t// Path routes\n\troutes := *t.Routes.Load()\n\tfor _, r := range routes {\n\t\tif !r.Install {\n\t\t\tcontinue\n\t\t}\n\n\t\tdr := &net.IPNet{\n\t\t\tIP:   r.Cidr.Masked().Addr().AsSlice(),\n\t\t\tMask: net.CIDRMask(r.Cidr.Bits(), r.Cidr.Addr().BitLen()),\n\t\t}","sourceCodeStart":547,"sourceCodeEnd":583,"githubUrl":"https://github.com/slackhq/nebula/blob/dd8f660c0ac37903ec4080ca4d3c861ba9342ceb/overlay/tun_linux.go#L547-L583","documentation":"Raised by tun.setDefaultRoute (called from reload and Activate) when applying the configured DefaultMTU to the detected default route fails. The message includes the MTU, the default route (dr), and the underlying error, so you can see exactly which route couldn't be modified.","triggerScenarios":"reload() or Activate() runs while the host's default route cannot have its MTU updated via netlink — route not found (wrong address family), permission denied, or the route changed concurrently.","commonSituations":"No IPv4/IPv6 default route on the host while the CIDR requires one; lack of CAP_NET_ADMIN; flapping default route (DHCP renewals, VPN-over-VPN) changing the route between lookup and update.","solutions":["Read dr and err in the message: if the route is 'none'/missing, ensure the host has a default route for that family.","Run with CAP_NET_ADMIN to allow route attribute changes.","Check that DefaultMTU in config is a valid MTU (e.g. 1300-1400 for overhead-heavy tunnels).","If the default route flaps (DHCP), retry reload after the network stabilizes.","Disable/adjust default-route MTU handling via config if your overlay doesn't need it."],"exampleFix":"// before\n# ip route  (no default route for the family)\n// after — provide a default route or set an explicit MTU\n# ip route add default via 10.0.0.1\ntun: { default_mtu: 1300 }","handlingStrategy":"retry","validationCode":"func defaultRouteExists(fam int) bool {\n    routes, err := netlink.RouteList(nil, fam)\n    if err != nil { return false }\n    for _, r := range routes {\n        if r.Dst == nil { return true } // default route\n    }\n    return false\n}","typeGuard":null,"tryCatchPattern":"if err := activateOverlay(); err != nil {\n    if strings.Contains(err.Error(), \"failed to set mtu\") && strings.Contains(err.Error(), \"default route\") {\n        time.Sleep(time.Second)\n        err = activateOverlay() // default route may have just flapped\n    }\n}","preventionTips":["Ensure a default route exists for both IPv4/IPv6 as needed","Set a valid tun.default_mtu in config","Run with CAP_NET_ADMIN","Retry on DHCP-driven default-route flaps"],"tags":["network","routing","mtu","netlink"],"backgroundTag":"route-mtu-update-failed","analyzedSha":"dd8f660c0ac37903ec4080ca4d3c861ba9342ceb","analyzedAt":"2026-09-03T11:13:55.444Z","contentChangedAt":"2026-09-03T11:13:55.444Z","schemaVersion":2},"datasetVersion":"2026-09-10T17:17:09.494Z"}