slackhq/nebula · error

failed to retrieve tun name: %w

Error message

failed to retrieve tun name: %w

What it means

After connecting to the utun control, newTun queries the assigned interface name with getsockopt(AF_SYS_CONTROL, _UTUN_OPT_IFNAME). If the kernel cannot report the interface name for this socket, this error wraps the errno. It means the utun connection exists but the kernel did not associate an interface name with it.

Source

Thrown at overlay/tun_darwin.go:115

	var ctlInfo = &unix.CtlInfo{}
	copy(ctlInfo.Name[:], utunControlName)

	err = unix.IoctlCtlInfo(fd, ctlInfo)
	if err != nil {
		return nil, fmt.Errorf("CTLIOCGINFO: %v", err)
	}

	err = unix.Connect(fd, &unix.SockaddrCtl{
		ID:   ctlInfo.Id,
		Unit: uint32(ifIndex) + 1,
	})
	if err != nil {
		return nil, fmt.Errorf("SYS_CONNECT: %v", err)
	}

	name, err = unix.GetsockoptString(fd, unix.AF_SYS_CONTROL, _UTUN_OPT_IFNAME)
	if err != nil {
		return nil, fmt.Errorf("failed to retrieve tun name: %w", err)
	}

	err = unix.SetNonblock(fd, true)
	if err != nil {
		return nil, fmt.Errorf("SetNonblock: %v", err)
	}

	t := &tun{
		f:           os.NewFile(uintptr(fd), ""),
		Device:      name,
		vpnNetworks: vpnNetworks,
		DefaultMTU:  c.GetInt("tun.mtu", DefaultMTU),
		l:           l,
	}

	err = t.reload(c, true)
	if err != nil {
		return nil, err

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Retry starting nebula — this is often transient kernel-state related.
2. Let macOS auto-select the unit (omit tun.dev) to reduce attach/teardown races with other VPNs.
3. Stop competing VPN clients (Cisco AnyConnect, iCloud Private Relay, etc.) that churn utun interfaces.
4. Update macOS; very old kernel versions may not support the ifname option reliably.

if err := start(); err != nil && strings.Contains(err.Error(), "failed to retrieve tun name") {
    // usually transient: retry with backoff before surfacing to the user
}

When it happens

Trigger: unix.GetsockoptString(fd, AF_SYS_CONTROL, _UTUN_OPT_IFNAME) returns an error right after a successful Connect — typically when the utun attach was torn down concurrently or the kernel state is inconsistent.

Common situations: Race with another VPN service destroying the utun just created; running on unusual/older macOS versions where the utun option behaves differently; heavily loaded hosts where the interface registration lagged.

Related errors

• system socket: %v
• CTLIOCGINFO: %v
• SYS_CONNECT: %v
• SetNonblock: %v
• unable to discover link_addr for tun interface

AI-assisted analysis of slackhq/nebula@dd8f660c0a (2026-09-03). Data as JSON: /api/errors/774dd44d1696134c. Report an issue: GitHub.