{"record":{"id":"ec1425dcf8b8c6ad","repo":"k3s-io/k3s","slug":"failed-to-determine-mtu-for-s-interface","errorCode":null,"errorMessage":"failed to determine MTU for %s interface","messagePattern":"failed to determine MTU for (.+?) interface","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/agent/flannel/flannel.go","lineNumber":171,"sourceCode":"\t\tif err != nil {\n\t\t\treturn nil, errors.WithMessagef(err, \"failed to find IPv4 address for interface %s\", iface.Name)\n\t\t}\n\t\tlogrus.Infof(\"The interface %s with ipv4 address %s will be used by flannel\", iface.Name, ifaceAddr[0])\n\t} else {\n\t\tifaceAddr = append(ifaceAddr, nil)\n\t}\n\tif nm.IPv6Enabled() {\n\t\tifacev6Addr, err = ip.GetInterfaceIP6Addrs(iface)\n\t\tif err != nil {\n\t\t\treturn nil, errors.WithMessagef(err, \"failed to find IPv6 address for interface %s\", iface.Name)\n\t\t}\n\t\tlogrus.Infof(\"The interface %s with ipv6 address %s will be used by flannel\", iface.Name, ifacev6Addr[0])\n\t} else {\n\t\tifacev6Addr = append(ifacev6Addr, nil)\n\t}\n\n\tif iface.MTU == 0 {\n\t\treturn nil, fmt.Errorf(\"failed to determine MTU for %s interface\", iface.Name)\n\t}\n\n\treturn &backend.ExternalInterface{\n\t\tIface:       iface,\n\t\tIfaceName:   iface.Name,\n\t\tIfaceAddr:   ifaceAddr[0],\n\t\tIfaceV6Addr: ifacev6Addr[0],\n\t\tExtAddr:     ifaceAddr[0],\n\t\tExtV6Addr:   ifacev6Addr[0],\n\t}, nil\n}\n\n// WriteSubnetFile atomically writes the flannel subnet configuration file.\n// Uses CreateTemp to avoid issues with pre-existing temp files (stale files\n// from crashes, unexpected permissions/ownership) and to ensure clean atomic\n// rename semantics with O_EXCL guarantees.\nfunc WriteSubnetFile(path string, nw ip.IP4Net, nwv6 ip.IP6Net, ipMasq bool, bn backend.Network, nm netMode) error {\n\tdir := filepath.Dir(path)","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/k3s-io/k3s/blob/6ba341e396edc16b8dcae978a7c5e3ac7ee5606e/pkg/agent/flannel/flannel.go#L153-L189","documentation":"While building flannel's backend.ExternalInterface, the agent reads the selected interface (auto-detected via default route, or --flannel-iface) and requires a positive MTU; if iface.MTU == 0 it fails immediately. Overlay backends derive packet sizing from the interface MTU, so 0 is unusable.","triggerScenarios":"The chosen interface reports MTU 0: some tun/dummy/veth devices, interfaces mid-creation or teardown, or NIC drivers that do not populate MTU. Auto-detection can also land on such an interface when the default route points through it.","commonSituations":"Pointing flannel at a VPN/tun interface; containerized or nested agents with virtual NICs; misbehaving drivers after resume/hotplug.","solutions":["Point flannel at a real interface with a sane MTU: --flannel-iface=eth0","Bring the selected interface fully up and verify 'ip link show <iface>' reports a non-zero MTU","Fix or replace the device/driver that reports MTU 0"],"exampleFix":"# before\n--flannel-iface tun0   # MTU 0\n\n# after\n--flancel-iface eth0    # typo-free: --flannel-iface eth0, MTU 1500","handlingStrategy":"validation","validationCode":"iface, err := net.InterfaceByName(name)\nif err != nil || iface.MTU <= 0 {\n    return fmt.Errorf(\"interface %s unusable for flannel (no MTU)\", name)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check 'ip link show <iface>' reports a non-zero MTU before selecting it with --flannel-iface","Avoid pointing flannel at tun/dummy devices that may report MTU 0"],"tags":["flannel","network","mtu","interface","config"],"backgroundTag":null,"analyzedSha":"6ba341e396edc16b8dcae978a7c5e3ac7ee5606e","analyzedAt":"2026-08-15T16:27:54.286Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}