What causes "failed to set tun v4 address: %s" in slackhq/nebula?

Check the wrapped errno (EEXIST => address already in use) and pick a non-conflicting tun IP range in the config.

failed to set tun v4 address: %s

Error message

failed to set tun v4 address: %s

What it means

activate4() assigns the IPv4 address and netmask to the utun device using the SIOCAIFADDR ioctl on an AF_INET control socket. This error wraps the errno when the kernel rejects the address assignment for one of the configured VPN networks. The address being set comes from tun routes in the nebula config, so a bad network specification commonly surfaces here.

Source

Thrown at overlay/tun_darwin.go:255

		Addr: unix.RawSockaddrInet4{
			Len:    unix.SizeofSockaddrInet4,
			Family: unix.AF_INET,
			Addr:   network.Addr().As4(),
		},
		DstAddr: unix.RawSockaddrInet4{
			Len:    unix.SizeofSockaddrInet4,
			Family: unix.AF_INET,
			Addr:   network.Addr().As4(),
		},
		MaskAddr: unix.RawSockaddrInet4{
			Len:    unix.SizeofSockaddrInet4,
			Family: unix.AF_INET,
			Addr:   prefixToMask(network).As4(),
		},
	}

	if err := ioctl(uintptr(s), unix.SIOCAIFADDR, uintptr(unsafe.Pointer(&ifr))); err != nil {
		return fmt.Errorf("failed to set tun v4 address: %s", err)
	}

	err = addRoute(network, t.linkAddr)
	if err != nil {
		return err
	}

	return nil
}

func (t *tun) activate6(network netip.Prefix) error {
	s, err := unix.Socket(
		unix.AF_INET6,
		unix.SOCK_DGRAM,
		unix.IPPROTO_IP,
	)
	if err != nil {
		return err

View on GitHub (pinned to dd8f660c0a)

Solutions

Check the wrapped errno (EEXIST => address already in use) and pick a non-conflicting tun IP range in the config.
Run nebula with sufficient privileges (root or CAP_NET_ADMIN equivalent) so SIOCAIFADDR is permitted.
Stop the other VPN or instance currently holding the address, then retry.
Validate the tun address/mask in the config is a well-formed IPv4 prefix.

Example fix

// before: address collides with the host LAN
tun:
  routes:
    - route: 192.168.1.0/24
// after: use a dedicated range for the overlay
tun:
  routes:
    - route: 10.100.0.0/16

Defensive patterns

Strategy: validation

Validate before calling

ip, err := netip.ParsePrefix(cfg.TunRoute)
if err != nil || !ip.Addr().Is4() {
    return fmt.Errorf("tun route must be a valid IPv4 prefix: %w", err)
}
// also confirm no other host interface already holds this address
out, _ := exec.Command("ifconfig", "-a").Output()
if strings.Contains(string(out), ip.Addr().String()) {
    return fmt.Errorf("address %s already assigned on host", ip.Addr())
}

Try / catch

if err := iface.Activate(); err != nil {
    if strings.Contains(err.Error(), "failed to set tun v4 address") {
        // EEXIST: pick a non-conflicting overlay range and retry
    }
    return err
}

Prevention

Use a dedicated overlay range (e.g. 10.x/16) that doesn't overlap host LANs
Run with root/admin privileges
Stop other VPN clients before starting nebula
Validate IPv4 prefixes in the config before launch

When it happens

Trigger: Activate() -> activate4() for each IPv4 vpnNetwork prefix; SIOCAIFADDR fails, e.g. the configured address is already assigned to another interface on the host, or the address/mask is invalid for the interface.

Common situations: The chosen tun IP (e.g. 10.x.x.x) collides with an existing host interface; another VPN client already holds the address; running two nebula instances with overlapping tun ranges; EPERM when lacking privileges.

Related errors

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