cilium/cilium · error

invalid MAC address for %s: %w

Error message

invalid MAC address for %s: %w

What it means

When creating the host endpoint, Cilium reads the hardware (MAC) address of the host device (defaults.HostDevice) via netlink and parses it with mac.FromHardwareAddr. If parsing fails, this error reports an invalid MAC address for the host device, and the host endpoint cannot be created.

Source

Thrown at pkg/endpoint/endpoint.go:714

	ep.IPv6 = ipv6

	ep.setState(StateWaitingForIdentity, "Ingress Endpoint creation")

	return ep, nil
}

// CreateHostEndpoint creates the endpoint corresponding to the host.
func CreateHostEndpoint(p EndpointParams,
	dnsRulesAPI DNSRulesAPI, proxy EndpointProxy,
	policyDebugLog io.Writer) (*Endpoint, error) {
	iface, err := safenetlink.LinkByName(defaults.HostDevice)
	if err != nil {
		return nil, err
	}

	hostMAC, err := mac.FromHardwareAddr(iface.Attrs().HardwareAddr)
	if err != nil {
		return nil, fmt.Errorf("invalid MAC address for %s: %w", defaults.HostDevice, err)
	}

	ep := createEndpoint(p, dnsRulesAPI, proxy, 0, defaults.HostDevice, policyDebugLog)
	ep.isHost = true
	ep.mac = hostMAC
	ep.nodeMAC = hostMAC
	ep.ifIndex = iface.Attrs().Index
	ep.DatapathConfiguration = NewDatapathConfiguration()

	ep.setState(StateWaitingForIdentity, "Endpoint creation")

	return ep, nil
}

// GetID returns the endpoint's ID as a 64-bit unsigned integer.
func (e *Endpoint) GetID() uint64 {
	return uint64(e.ID)
}

View on GitHub (pinned to ac7b90affa)

Solutions

1. Verify the device configured via --host-device exists and has a valid MAC (ip link show <device>).
2. Ensure the device is a standard Ethernet-like interface; if using a custom device, confirm its HardwareAddr is 6 bytes.
3. Correct the --host-device flag to point at the intended interface (e.g. eth0 or the chosen datapath device).
4. Restart cilium-agent after fixing the device configuration.

iface, err := netlink.LinkByName(hostDevice)
if err != nil {
    return fmt.Errorf("host device %s not found", hostDevice)
}
mac := iface.Attrs().HardwareAddr
if len(mac) != 6 {
    return fmt.Errorf("host device %s has invalid MAC length %d", hostDevice, len(mac))
}

func validMAC(a net.HardwareAddr) bool { return len(a) == 6 }

if _, err := CreateHostEndpoint(...); err != nil {
    if strings.Contains(err.Error(), "invalid MAC address") {
        log.Printf("host device %s lacks a valid MAC; choose a standard Ethernet device", defaults.HostDevice)
    }
}

When it happens

Trigger: iface.Attrs().HardwareAddr is empty, malformed (wrong length, not 6 bytes) or otherwise unparseable — typically because the host device named by --host-device does not exist as expected or is an unusual virtual interface.

Common situations: Misconfigured host-device flag pointing to a interface with no MAC; unusual tunnel/bond devices; kernel returning empty HardwareAddr for the device; running in environments with exotic veth setups.

Related errors

• invalid MAC address for %s: %w
• unable to set MAC address on interface %s: %w
• an unsupported XfrmStateAlgo combination has been found
• no message nor error from netlink
• error getting IPsec decryption interfaces: %w

AI-assisted analysis of cilium/cilium@ac7b90affa (2026-08-31). Data as JSON: /api/errors/0e28146c6f06fa65. Report an issue: GitHub.