{"record":{"id":"8341d59a273cb187","repo":"cilium/cilium","slug":"failed-to-set-mtu-d-for-s-w","errorCode":null,"errorMessage":"failed to set MTU %d for %s: %w","messagePattern":"failed to set MTU (.+?) for (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/loader/netlink.go","lineNumber":148,"sourceCode":"// the first step of datapath initialization, then performs the setup (and\n// creation, if needed) of those interfaces. It returns two links and an error.\n// By default, it sets up the veth pair - cilium_host and cilium_net.\nfunc setupBaseDevice(logger *slog.Logger, sysctl sysctl.Sysctl, mtu int) (netlink.Link, netlink.Link, error) {\n\tif err := setupVethPair(logger, sysctl, defaults.HostDevice, defaults.SecondHostDevice); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to setup veth pair: %w\", err)\n\t}\n\n\tlinkHost, err := safenetlink.LinkByName(defaults.HostDevice)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to get link for %s: %w\", defaults.HostDevice, err)\n\t}\n\tlinkNet, err := safenetlink.LinkByName(defaults.SecondHostDevice)\n\tif err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to get link for %s: %w\", defaults.SecondHostDevice, err)\n\t}\n\n\tif err := netlink.LinkSetMTU(linkHost, mtu); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to set MTU %d for %s: %w\", mtu, linkHost.Attrs().Name, err)\n\t}\n\tif err := netlink.LinkSetMTU(linkNet, mtu); err != nil {\n\t\treturn nil, nil, fmt.Errorf(\"failed to set MTU %d for %s: %w\", mtu, linkNet.Attrs().Name, err)\n\t}\n\n\treturn linkHost, linkNet, nil\n}\n\n// addHostDeviceAddr add internal ipv4 and ipv6 addresses to the cilium_host device.\nfunc addHostDeviceAddr(hostDev netlink.Link, ipv4, ipv6 net.IP) error {\n\tif ipv4 != nil {\n\t\taddr := netlink.Addr{\n\t\t\tIPNet: &net.IPNet{\n\t\t\t\tIP:   ipv4,\n\t\t\t\tMask: net.CIDRMask(32, 32), // corresponds to /32\n\t\t\t},\n\t\t}\n","sourceCodeStart":130,"sourceCodeEnd":166,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/loader/netlink.go#L130-L166","documentation":"setupBaseDevice sets the configured MTU on cilium_host with netlink.LinkSetMTU. When the kernel rejects the MTU change on the host device, this wrapped error is returned with the MTU value and device name. It means datapath initialization aborts because the interface MTU could not be applied.","triggerScenarios":"netlink.LinkSetMTU(linkHost, mtu) fails on cilium_host — typically EINVAL for an MTU outside the device's allowed range, or the device disappeared mid-setup.","commonSituations":"Misconfigured --agent-not-ready-tolerate- MTU / tunnel MTU values (e.g. 0 or huge values like 65535) exceeding what veth/cilium_host accepts; encapsulation overhead making the requested MTU larger than the underlying NIC supports; race where the device was deleted between lookup and set.","solutions":["Check the configured MTU option and set a valid value (typically 1500, or physical MTU minus encapsulation overhead).","Inspect the wrapped kernel error: EINVAL means out-of-range MTU; ENODEV means the link vanished — restart to recreate the pair.","When using Geneve/VXLAN with big TCP or custom MTU, compute overhead correctly (e.g. 1500 - 50 for Geneve over IPv4).","Ensure nothing concurrently deletes cilium_host during startup."],"exampleFix":"// before\ncilium-agent --mtu 9000   # underlying NIC MTU is 1500\n// after\ncilium-agent --mtu 1500   # or 1450 for VXLAN/GENEVE overhead over a 1500 NIC","handlingStrategy":"validation","validationCode":"// validate MTU before calling into the loader\nphysMTU, _ := getNicMTU(primaryDevice)\nmaxMTU := physMTU - tunnelOverhead(mode) // e.g. 50 for Geneve\nif mtu <= 0 || mtu > maxMTU {\n    return fmt.Errorf(\"configured MTU %d out of range (max %d)\", mtu, maxMTU)\n}","typeGuard":null,"tryCatchPattern":"if err := netlink.LinkSetMTU(linkHost, mtu); err != nil {\n    if errors.Is(err, unix.EINVAL) {\n        return fmt.Errorf(\"MTU %d invalid for %s; check device limits\", mtu, linkHost.Attrs().Name)\n    }\n    return err\n}","preventionTips":["Set MTU explicitly and compute tunnel overhead (VXLAN/Geneve ~50 bytes).","Never configure MTU 0 or larger than the physical NIC supports.","Validate MTU config in Helm values/agent flags before deploy."],"tags":["network","mtu","netlink","cilium"],"backgroundTag":"mtu-configuration-invalid","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T22:30:34.772Z"}