{"record":{"id":"ec762ef0298b2cc3","repo":"cilium/cilium","slug":"setting-mtu-on-s-w","errorCode":null,"errorMessage":"setting MTU on %s: %w","messagePattern":"setting MTU on (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/loader/netlink.go","lineNumber":487,"sourceCode":"\t\t\treturn nil, fmt.Errorf(\"creating device %s: %w\", name, err)\n\t\t}\n\n\t\t// Fetch the link we've just created.\n\t\tl, err = safenetlink.LinkByName(name)\n\t\tif err != nil {\n\t\t\treturn nil, fmt.Errorf(\"retrieving created device %s: %w\", name, err)\n\t\t}\n\t}\n\n\tif err := enableForwarding(logger, sysctl, l); err != nil {\n\t\treturn nil, fmt.Errorf(\"setting up device %s: %w\", name, err)\n\t}\n\n\t// Update MTU on the link if necessary.\n\twantMTU, gotMTU := attrs.Attrs().MTU, l.Attrs().MTU\n\tif wantMTU != 0 && wantMTU != gotMTU {\n\t\tif err := netlink.LinkSetMTU(l, wantMTU); err != nil {\n\t\t\treturn nil, fmt.Errorf(\"setting MTU on %s: %w\", name, err)\n\t\t}\n\t}\n\n\treturn l, nil\n}\n\n// removeDevice removes the device with the given name. Returns error if the\n// device exists but was unable to be removed.\nfunc removeDevice(name string) error {\n\tlink, err := safenetlink.LinkByName(name)\n\tif err != nil {\n\t\treturn nil\n\t}\n\n\tif err := netlink.LinkDel(link); err != nil {\n\t\treturn fmt.Errorf(\"removing device %s: %w\", name, err)\n\t}\n","sourceCodeStart":469,"sourceCodeEnd":505,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/loader/netlink.go#L469-L505","documentation":"netlink.LinkSetMTU failed while aligning the tunnel device's MTU with the configured value. Cilium compares the desired MTU (from CiliumConfig) with the link's actual MTU and sets it if they differ; the kernel rejected the RTM_SETLINK MTU change.","triggerScenarios":"Called from ensureDevice (setupGeneveDevice/setupVxlanDevice/setupIPIPDevices) when wantMTU != 0, differs from the current link MTU, and netlink.LinkSetMTU returns e.g. EINVAL (MTU below device minimum / above max for encapsulation overhead) or ENODEV (link deleted concurrently).","commonSituations":"Users configuring a custom MTU in the CiliumConfig that is invalid for Geneve/VXLAN overhead (e.g. larger than underlying NIC minus 50-byte overhead), or IPIP devices with very low minimum MTU limits.","solutions":["Lower or remove the custom MTU in the CiliumConfig so Cilium auto-computes it from the native device MTU minus encapsulation overhead.","Check that the underlying physical NIC MTU can accommodate the tunnel overhead (MTU_outer - 50 for VXLAN/Geneve, -20 for IPIP).","Verify the device still exists (concurrent deletion) and restart the agent to retry.","Inspect the wrapped netlink errno in logs to distinguish EINVAL (bad value) from ENODEV (missing link)."],"exampleFix":"# before: explicit MTU too large for tunnel overhead\ncilium-config: mtu: \"9001\"\n# after: let Cilium derive tunnel MTU, or size it for 50-byte overhead\ncilium-config: mtu: \"8951\"  # 9001 - 50 (VXLAN/Geneve overhead)","handlingStrategy":"validation","validationCode":"wantMTU := 8951 // outer NIC MTU 9001 minus 50B VXLAN/Geneve overhead\nif wantMTU > 9001-50 {\n\treturn fmt.Errorf(\"MTU %d too large for tunnel encapsulation overhead\", wantMTU)\n}","typeGuard":null,"tryCatchPattern":"if err := setupVxlanDevice(...); err != nil {\n\tif strings.Contains(err.Error(), \"setting MTU\") {\n\t\tlog.Printf(\"configured MTU rejected by kernel; falling back to auto MTU: %v\", err)\n\t}\n\treturn err\n}","preventionTips":["Subtract encapsulation overhead (50B VXLAN/Geneve, 20B IPIP) from the native NIC MTU when setting a custom MTU.","Prefer letting Cilium auto-compute MTU instead of hardcoding it.","Check NIC MTU with `ip link` before configuring tunnel MTU.","Validate MTU changes with `ip link set dev cilium_vxlan mtu N` manually before applying them via config."],"tags":["network","mtu","netlink","cilium"],"backgroundTag":"mtu-configuration-invalid","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}