k3s-io/k3s · error

failed to determine MTU for %s interface

Error message

failed to determine MTU for %s interface

What it means

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.

Source

Thrown at pkg/agent/flannel/flannel.go:171

		if err != nil {
			return nil, errors.WithMessagef(err, "failed to find IPv4 address for interface %s", iface.Name)
		}
		logrus.Infof("The interface %s with ipv4 address %s will be used by flannel", iface.Name, ifaceAddr[0])
	} else {
		ifaceAddr = append(ifaceAddr, nil)
	}
	if nm.IPv6Enabled() {
		ifacev6Addr, err = ip.GetInterfaceIP6Addrs(iface)
		if err != nil {
			return nil, errors.WithMessagef(err, "failed to find IPv6 address for interface %s", iface.Name)
		}
		logrus.Infof("The interface %s with ipv6 address %s will be used by flannel", iface.Name, ifacev6Addr[0])
	} else {
		ifacev6Addr = append(ifacev6Addr, nil)
	}

	if iface.MTU == 0 {
		return nil, fmt.Errorf("failed to determine MTU for %s interface", iface.Name)
	}

	return &backend.ExternalInterface{
		Iface:       iface,
		IfaceName:   iface.Name,
		IfaceAddr:   ifaceAddr[0],
		IfaceV6Addr: ifacev6Addr[0],
		ExtAddr:     ifaceAddr[0],
		ExtV6Addr:   ifacev6Addr[0],
	}, nil
}

// WriteSubnetFile atomically writes the flannel subnet configuration file.
// Uses CreateTemp to avoid issues with pre-existing temp files (stale files
// from crashes, unexpected permissions/ownership) and to ensure clean atomic
// rename semantics with O_EXCL guarantees.
func WriteSubnetFile(path string, nw ip.IP4Net, nwv6 ip.IP6Net, ipMasq bool, bn backend.Network, nm netMode) error {
	dir := filepath.Dir(path)

View on GitHub (pinned to 6ba341e396)

Solutions

1. Point flannel at a real interface with a sane MTU: --flannel-iface=eth0
2. Bring the selected interface fully up and verify 'ip link show <iface>' reports a non-zero MTU
3. Fix or replace the device/driver that reports MTU 0

Example fix

# before
--flannel-iface tun0   # MTU 0

# after
--flancel-iface eth0    # typo-free: --flannel-iface eth0, MTU 1500

iface, err := net.InterfaceByName(name)
if err != nil || iface.MTU <= 0 {
    return fmt.Errorf("interface %s unusable for flannel (no MTU)", name)
}

When it happens

Trigger: 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.

Common situations: Pointing flannel at a VPN/tun interface; containerized or nested agents with virtual NICs; misbehaving drivers after resume/hotplug.

Related errors

• Flannel configuration not defined
• no IPv6 CIDRs found
• VPN Error. Tailscale requires a JoinKey
• invalid node-external-ip: %w
• unsupported flannel backend '%s' for Windows

AI-assisted analysis of k3s-io/k3s@6ba341e396 (2026-08-15). Data as JSON: /api/errors/ec1425dcf8b8c6ad. Report an issue: GitHub.