{"record":{"id":"29376616c1c7d9fa","repo":"cilium/cilium","slug":"attaching-xdp-program-to-interface-s-w","errorCode":null,"errorMessage":"attaching XDP program to interface %s: %w","messagePattern":"attaching XDP program to interface (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/datapath/loader/base.go","lineNumber":277,"sourceCode":"\t\treturn nil\n\t}\n\tfor _, dev := range devices {\n\t\t// When WG & encrypt-node are on, the devices include cilium_wg0 to attach cil_from_wireguard\n\t\t// so that NodePort's rev-{S,D}NAT translations happens for a reply from the remote node.\n\t\t// So We need to exclude cilium_wg0 not to attach the XDP program when XDP acceleration\n\t\t// is enabled, otherwise we will get \"operation not supported\" error.\n\t\tif dev == wgTypes.IfaceName {\n\t\t\tcontinue\n\t\t}\n\n\t\tif err := compileAndLoadXDPProg(ctx, logger, reg, collLoader, lnc, dev, xdpConfig.Mode()); err != nil {\n\t\t\tif option.Config.NodePortAcceleration == option.XDPModeBestEffort {\n\t\t\t\tlogger.Info(\"Failed to attach XDP program, ignoring due to best-effort mode\",\n\t\t\t\t\tlogfields.Error, err,\n\t\t\t\t\tlogfields.Device, dev,\n\t\t\t\t)\n\t\t\t} else {\n\t\t\t\treturn fmt.Errorf(\"attaching XDP program to interface %s: %w\", dev, err)\n\t\t\t}\n\t\t}\n\t}\n\n\treturn nil\n}\n\nfunc (l *loader) ReinitializeHostDev(ctx context.Context, mtu int) error {\n\t_, _, err := setupBaseDevice(l.logger, l.sysctl, mtu)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to setup base devices: %w\", err)\n\t}\n\n\treturn nil\n}\n\n// Reinitialize (re-)configures the base datapath configuration including global\n// BPF programs, netfilter rule configuration and reserving routes in IPAM for","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/cilium/cilium/blob/ac7b90affa4baf0642e6685319d56907b3a73a6d/pkg/datapath/loader/base.go#L259-L295","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set --acceleration-mode=best-effort so unsupported devices are skipped instead of failing startup","Check the wrapped error and device name to identify the failing interface and its driver XDP support","Verify the NIC driver supports native XDP (ethtool -i <dev>; driver docs)","Ensure bpffs is mounted and the kernel meets XDP requirements","Disable XDP acceleration (--acceleration-mode=disabled) if not required"],"exampleFix":"// before\nacceleration-mode: native\n// after (tolerate devices without native XDP)\nacceleration-mode: best-effort","handlingStrategy":"fallback","validationCode":"// check native XDP support per device before enabling acceleration\nfunc supportsNativeXDP(dev string) bool {\n\tlink, err := safenetlink.LinkByName(dev)\n\treturn err == nil && link.Attrs().EncapType != \"\" // plus driver check via ethtool\n}","typeGuard":"func isXDPAttachError(err error) (string, bool) {\n\tvar dev string\n\t_, scanErr := fmt.Sscanf(err.Error(), \"attaching XDP program to interface %s\", &dev)\n\treturn dev, scanErr == nil\n}","tryCatchPattern":"if err := reinitializeXDPLocked(ctx, logger, reg, collLoader, lnc, devices); err != nil {\n\tif !isBestEffort() {\n\t\t// surface device name from error for operator remediation\n\t\treturn fmt.Errorf(\"xdp init: %w\", err)\n\t}\n\tlogger.Warn(\"continuing without XDP acceleration\", \"err\", err)\n}","preventionTips":["Use --acceleration-mode=best-effort unless you have verified native XDP support on all devices","Check NIC driver XDP support (native vs generic) before production rollout","Exclude veth/overlay devices from --devices when using XDP","Ensure bpffs mount and kernel XDP helper availability in CI smoke tests"],"tags":["network","xdp","bpf","datapath","cilium"],"backgroundTag":"bpf-program-attach-failed","analyzedSha":"ac7b90affa4baf0642e6685319d56907b3a73a6d","analyzedAt":"2026-08-31T18:27:15.868Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}