cilium/cilium · error

create netlink handle: %w

Error message

create netlink handle: %w

What it means

Within HaveBIGTCPTunnel, a netlink handle is created inside the probe network namespace via netlink.NewHandle(). Failure to open a rtnetlink socket is wrapped as 'create netlink handle'.

Source

Thrown at pkg/datapath/linux/probes/probes.go:808

	} else {
		return ErrNotSupported
	}
})

// Probes whether the kernel supports BIG TCP for VXLAN and GENEVE.
var HaveBIGTCPTunnel = sync.OnceValue(func() error {
	ns, err := netns.New()
	if err != nil {
		return fmt.Errorf("create netns: %w", err)
	}
	defer ns.Close()

	var h *netlink.Handle
	if err := ns.Do(func() (err error) {
		h, err = netlink.NewHandle()
		return err
	}); err != nil {
		return fmt.Errorf("create netlink handle: %w", err)
	}
	defer h.Close()

	const probeNetdev = "probe"

	dev := &netlink.Geneve{
		LinkAttrs: netlink.LinkAttrs{
			Name: probeNetdev,
		},
		Dport: defaults.TunnelPortGeneve,
	}

	if err := h.LinkAdd(dev); err != nil {
		return fmt.Errorf("failed to create a probe GENEVE device: %w", err)
	}

	link, err := safenetlink.WithRetryResult(func() (netlink.Link, error) {
		//nolint:forbidigo

View on GitHub (pinned to ac7b90affa)

Solutions

1. Add CAP_NET_ADMIN to the process
2. Check ulimit -n for fd exhaustion
3. Verify seccomp/SELinux policy allows socket(AF_NETLINK, NETLINK_ROUTE)
4. Confirm kernel rtnetlink support

// open a rtnetlink socket to verify netlink is usable
h, err := netlink.NewHandle()
if err != nil { return fmt.Errorf("netlink unavailable: %w", err) }
h.Close()

var syscallErrno syscall.Errno
if errors.As(err, &syscallErrno) && syscallErrno == syscall.EMFILE { /* fd exhaustion */ }

if err := probes.HaveBIGTCPTunnel(); err != nil {
    if strings.Contains(err.Error(), "create netlink handle") { /* check caps/fds/seccomp */ }
    return err
}

When it happens

Trigger: netlink.NewHandle() inside ns.Do fails — typically due to missing CAP_NET_ADMIN in the new namespace or rtnetlink socket creation being restricted.

Common situations: Containers lacking NET_ADMIN; SELinux/seccomp blocking NETLINK_ROUTE socket creation; file descriptor exhaustion (EMFILE).

Related errors

• failed to create a probe GENEVE device: %w
• Failed to generate per interface tc commands: %s
• cannot get xfrm state: %w
• failed to remove IP %s: %w
• unable to lookup netkit peer link: %w

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