unable to determine MAC address of veth pair on the containe

Error message

unable to determine MAC address of veth pair on the container side

What it means

During CNI ADD the plugin validates the container-side veth MAC (vethLXCMac). If it is invalid, Cilium cannot register the endpoint with the agent because endpoint identity/monitoring relies on the container MAC. ADD is aborted before the EndpointChangeRequest is sent.

Source

Thrown at plugins/cilium-cni/chaining/generic-veth/generic-veth.go:196

	peer, err = netlink.LinkByIndex(peerIndex)
	if err != nil {
		err = fmt.Errorf("unable to lookup link %d: %w", peerIndex, err)
		return
	}

	hostMac, _ = mac.FromHardwareAddr(peer.Attrs().HardwareAddr)
	vethHostName = peer.Attrs().Name
	vethHostIdx = peer.Attrs().Index

	switch {
	case vethHostName == "":
		err = errors.New("unable to determine name of veth pair on the host side")
		return
	case !hostMac.IsValid():
		err = errors.New("unable to determine MAC address of veth pair on the host side")
		return
	case !vethLXCMac.IsValid():
		err = errors.New("unable to determine MAC address of veth pair on the container side")
		return
	case vethIP == "" && vethIPv6 == "":
		err = errors.New("unable to determine IP address of the container")
		return
	case vethHostIdx == 0:
		err = errors.New("unable to determine index interface of veth pair on the host side")
		return
	}

	var disabled = false
	ep := &models.EndpointChangeRequest{
		Addressing: &models.AddressPair{
			IPv4: vethIP,
			IPv6: vethIPv6,
		},
		ContainerID:            pluginCtx.Args.ContainerID,
		State:                  models.EndpointStateWaitingDashForDashIdentity.Pointer(),
		HostMac:                hostMac,

View on GitHub (pinned to ac7b90affa)

Solutions

Retry the pod schedule; transient link states often resolve.
Verify the CNI chain configuration so cilium-cni runs against a standard veth-based interface.
Check that no mutating plugin (e.g. macvlan/bond setup) precedes the cilium chain step and strips the MAC.
Capture netlink state at failure time via CNI debug logs.

Defensive patterns

Strategy: validation

Prevention

Ensure cilium-cni runs against a standard veth-based interface in the CNI chain.
Avoid chained plugins that mutate the container interface MAC.
Keep runtime/CNI versions aligned and retry transient link-state races.

When it happens

Trigger: In generic-veth.go Add(): the container-side interface's hardware address failed mac.IsValid() — e.g. the netlink link for the container interface has no hardware address.

Common situations: Custom runtimes or nested containers presenting interfaces without MACs; misconfigured chaining where an earlier plugin already altered the link; concurrent link modification during ADD.

Related errors

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