slackhq/nebula · error

unable to create AF_ROUTE socket: %v

Error message

unable to create AF_ROUTE socket: %v

What it means

addRoute adds a kernel route by sending a routing socket message over a raw AF_ROUTE socket. If unix.Socket(AF_ROUTE, SOCK_RAW, AF_UNSPEC) fails, this error wraps the errno. Without a routing socket the library cannot program routes, so the route add aborts.

Source

Thrown at overlay/tun_freebsd.go:617

			t.l.Error("Failed to remove route", "error", err, "route", r)
		} else {
			t.l.Info("Removed route", "route", r)
		}
	}
	return nil
}

func (t *tun) deviceBytes() (o [16]byte) {
	for i, c := range t.Device {
		o[i] = byte(c)
	}
	return
}

func addRoute(prefix netip.Prefix, gateway netroute.Addr) error {
	sock, err := unix.Socket(unix.AF_ROUTE, unix.SOCK_RAW, unix.AF_UNSPEC)
	if err != nil {
		return fmt.Errorf("unable to create AF_ROUTE socket: %v", err)
	}
	defer unix.Close(sock)

	route := &netroute.RouteMessage{
		Version: unix.RTM_VERSION,
		Type:    unix.RTM_ADD,
		Flags:   unix.RTF_UP,
		Seq:     1,
	}

	if prefix.Addr().Is4() {
		route.Addrs = []netroute.Addr{
			unix.RTAX_DST:     &netroute.Inet4Addr{IP: prefix.Masked().Addr().As4()},
			unix.RTAX_NETMASK: &netroute.Inet4Addr{IP: prefixToMask(prefix).As4()},
			unix.RTAX_GATEWAY: gateway,
		}
	} else {
		route.Addrs = []netroute.Addr{

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Run the process as root or with equivalent privileges to manage the routing table
2. Check the wrapped errno: EACCES/EPERM → privileges; EMFILE/ENFILE → fd limits
3. If running in a jail, verify the jail permits raw socket creation (allow.raw_sockets / vnet)
4. Pre-create routes manually with `route add` if you cannot grant privileges, and skip route programming

// pre-check privilege on unix via a probe socket
if probe, err := unix.Socket(unix.AF_ROUTE, unix.SOCK_RAW, unix.AF_UNSPEC); err != nil {
    return fmt.Errorf("routing sockets unavailable (need root/jail raw-socket allowance): %w", err)
} else {
    unix.Close(probe)
}

if err := addRoute(prefix, gw); err != nil {
    if strings.Contains(err.Error(), "unable to create AF_ROUTE socket") {
        log.Error("cannot create routing socket; run privileged or pre-add routes manually", "err", err)
        return err
    }
}

When it happens

Trigger: unix.Socket for the routing socket returns an error during addRoute (invoked from addRoutes after Activate) — most commonly EPERM/EACCES for an unprivileged process, or resource exhaustion.

Common situations: Running the tunnel daemon as a non-root user without route-management privileges; FreeBSD jails/security.mac restricting raw socket creation; fd exhaustion; hardened seclevel settings disallowing raw sockets.

Related errors

• unable to create AF_ROUTE socket: %v
• failed to create route.RouteMessage: %w
• failed to create route.RouteMessage for change: %w
• failed to write route.RouteMessage to socket: %w
• ErrInvalidIPv6RemoteForSocket

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