cilium/cilium · error

attaching XDP program to interface %s: %w

Error message

attaching XDP program to interface %s: %w

What it means

Raised by reinitializeXDPLocked when compileAndLoadXDPProg fails to attach the XDP program to a device, and NodePortAcceleration is not 'best-effort'. In best-effort mode the failure is logged and skipped; in native/preferred mode it aborts Reinitialize. The wrapped error typically comes from BPF compilation or netlink XDP attach.

Source

Thrown at pkg/datapath/loader/base.go:277

		return nil
	}
	for _, dev := range devices {
		// When WG & encrypt-node are on, the devices include cilium_wg0 to attach cil_from_wireguard
		// so that NodePort's rev-{S,D}NAT translations happens for a reply from the remote node.
		// So We need to exclude cilium_wg0 not to attach the XDP program when XDP acceleration
		// is enabled, otherwise we will get "operation not supported" error.
		if dev == wgTypes.IfaceName {
			continue
		}

		if err := compileAndLoadXDPProg(ctx, logger, reg, collLoader, lnc, dev, xdpConfig.Mode()); err != nil {
			if option.Config.NodePortAcceleration == option.XDPModeBestEffort {
				logger.Info("Failed to attach XDP program, ignoring due to best-effort mode",
					logfields.Error, err,
					logfields.Device, dev,
				)
			} else {
				return fmt.Errorf("attaching XDP program to interface %s: %w", dev, err)
			}
		}
	}

	return nil
}

func (l *loader) ReinitializeHostDev(ctx context.Context, mtu int) error {
	_, _, err := setupBaseDevice(l.logger, l.sysctl, mtu)
	if err != nil {
		return fmt.Errorf("failed to setup base devices: %w", err)
	}

	return nil
}

// Reinitialize (re-)configures the base datapath configuration including global
// BPF programs, netfilter rule configuration and reserving routes in IPAM for

View on GitHub (pinned to ac7b90affa)

Solutions

1. Set --acceleration-mode=best-effort so unsupported devices are skipped instead of failing startup
2. Check the wrapped error and device name to identify the failing interface and its driver XDP support
3. Verify the NIC driver supports native XDP (ethtool -i <dev>; driver docs)
4. Ensure bpffs is mounted and the kernel meets XDP requirements
5. Disable XDP acceleration (--acceleration-mode=disabled) if not required

Example fix

// before
acceleration-mode: native
// after (tolerate devices without native XDP)
acceleration-mode: best-effort

// check native XDP support per device before enabling acceleration
func supportsNativeXDP(dev string) bool {
	link, err := safenetlink.LinkByName(dev)
	return err == nil && link.Attrs().EncapType != "" // plus driver check via ethtool
}

func isXDPAttachError(err error) (string, bool) {
	var dev string
	_, scanErr := fmt.Sscanf(err.Error(), "attaching XDP program to interface %s", &dev)
	return dev, scanErr == nil
}

if err := reinitializeXDPLocked(ctx, logger, reg, collLoader, lnc, devices); err != nil {
	if !isBestEffort() {
		// surface device name from error for operator remediation
		return fmt.Errorf("xdp init: %w", err)
	}
	logger.Warn("continuing without XDP acceleration", "err", err)
}

When it happens

Trigger: XDP acceleration enabled (--acceleration-mode=native or preferred) and compileAndLoadXDPProg fails for a configured device, e.g. driver lacks native XDP support, device doesn't exist, or compilation fails.

Common situations: NIC driver without native XDP (e.g. some virtual/bonded interfaces) while acceleration-mode=native; running in containers/VMs (veth) that only support generic XDP; missing bpffs mount; kernel too old for required XDP helpers.

Related errors

• failed to load wireguard programs: %w
• interface %s ingress: %w
• program %s has unspecified type: annotate with __section_ent
• unable to list %s chain: %s (%w)
• unable to add %s chain: %s (%w)

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