kubernetes/kops · error

no physical network interface found with MAC address %q

Error message

no physical network interface found with MAC address %q

What it means

After scanning physical interfaces (those with a 'device' symlink in sysfs), no entry's 'address' equaled the MAC fetched from IMDS. nodeup refuses to write 75-eni-secondary.network because a wrong match would make systemd-networkd ignore the primary interface and break DNS via systemd-resolved. This is a deliberate safety failure, not a crash.

Source

Thrown at nodeup/pkg/model/networking/eni_networking.go:238

		name := entry.Name()
		// The scan uses the "device" symlink in sysfs to know if an interface is physical.
		if _, err := os.Stat(filepath.Join(sysClassNet, name, "device")); err != nil {
			continue
		}
		address, err := os.ReadFile(filepath.Join(sysClassNet, name, "address"))
		if err != nil {
			continue
		}
		if strings.EqualFold(strings.TrimSpace(string(address)), mac) {
			matches = append(matches, name)
		}
	}

	switch len(matches) {
	case 1:
		return matches[0], nil
	case 0:
		return "", fmt.Errorf("no physical network interface found with MAC address %q", mac)
	default:
		return "", fmt.Errorf("multiple physical network interfaces found with MAC address %q: %v", mac, matches)
	}
}

// narrowCloudIfupdownHelperRule rewrites Debian 11's
// /etc/udev/rules.d/75-cloud-ifupdown.rules to exclude AWS VPC CNI veths.
// The package-shipped rule matches ENV{INTERFACE}=="eth*|en*", which catches
// real ENIs (ens*) and CNI veths (eni*) alike. For each new netdev,
// /etc/network/cloud-ifupdown-helper generates a DHCP ifupdown stanza and
// starts ifup@$IFACE.service. On CNI veths DHCP times out, ifdown then takes
// the veth DOWN, and pod networking is broken.
//
// The rule and helper are written by cloud-init at first boot and are not
// owned by any dpkg package, so overwriting the file is safe.
//
// Debian 11 only.
func narrowCloudIfupdownHelperRule(c *fi.NodeupModelBuilderContext, dist distributions.Distribution) {

View on GitHub (pinned to 4c8573c808)

Solutions

1. Compare IMDS MAC to sysfs: for i in /sys/class/net/*; do echo "$i $(cat $i/address)"; done and reconcile mismatches
2. Confirm the instance uses ENA and the primary NIC exposes /sys/class/net/<name>/device (ls -l /sys/class/net/*/device)
3. Check for bonding/bridging that moved the ENI MAC onto a virtual device — adjust instance networking or run nodeup earlier in boot
4. Reboot the node to resync IMDS-visible and sysfs state, then re-run nodeup

Example fix

// diagnostic
mac=$(TOKEN=$(curl -sX PUT http://169.254.169.254/latest/api/token); curl -sH "X-aws-ec2-metadata-token: $TOKEN" http://169.254.169.254/latest/meta-data/mac)
grep -ri "$mac" /sys/class/net/*/address  # expect exactly one physical match

When it happens

Trigger: The MAC from IMDS 'mac' matches zero physical interfaces in /sys/class/net: the scan found no interface whose sysfs address file equals the IMDS MAC (case-insensitive), e.g. interface renamed/replaced after IMDS read, MAC truncated/misparsed, or IMDS returned the MAC of a bond/parent not present as a physical device.

Common situations: Non-ENA or virtualized NICs where the interface lacks a 'device' symlink; systems where IMDS mac disagrees with sysfs due to bonding or hot-swap; running nodeup somewhere that is not the actual EC2 instance; custom kernel modules that hide the device link.

Related errors

• reading %s: %w
• error querying kubernetes version: %v
• error loading channel %q: %v
• error querying ec2 metadata service (for region): %v
• listing nodes in cluster: %v

AI-assisted analysis of kubernetes/kops@4c8573c808 (2026-09-05). Data as JSON: /api/errors/fbe849b4a6c708eb. Report an issue: GitHub.