slackhq/nebula · error

unable to create AF_ROUTE socket: %v

Error message

unable to create AF_ROUTE socket: %v

What it means

addRoute() programs a kernel route by opening a raw AF_ROUTE routing socket and sending an RTM_ADD message. This error is returned when unix.Socket(AF_ROUTE, SOCK_RAW, AF_UNSPEC) fails, i.e. a routing socket could not be created at all, before any route message is built or sent.

Source

Thrown at overlay/tun_darwin.go:425

	for _, r := range routes {
		if !r.Install {
			continue
		}

		err := delRoute(r.Cidr, t.linkAddr)
		if err != nil {
			t.l.Error("Failed to remove route", "error", err, "route", r)
		} else {
			t.l.Info("Removed route", "route", r)
		}
	}
	return nil
}

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 nebula as root (or with the privileges required to open routing sockets on macOS).
2. Check the wrapped errno: EPERM => insufficient privileges; EMFILE/ENFILE => raise `ulimit -n` / system file limit.
3. Verify the sandbox/container policy permits AF_ROUTE sockets; move nebula to the host if it does not.
4. Restart the host if the routing socket table is exhausted (kernel-level ENOBUFS).

Example fix

// before
$ ./nebula -config config.yaml
// after
$ sudo ./nebula -config config.yaml

var rerr error
for i := 0; i < 3; i++ {
    rerr = iface.Activate()
    if rerr == nil || !strings.Contains(rerr.Error(), "unable to create AF_ROUTE socket") {
        break
    }
    time.Sleep(200 * time.Millisecond) // transient EMFILE/ENOBUFS
}
return rerr

When it happens

Trigger: Called from activate4() or addRoutes(); unix.Socket returns an error, typically EPERM because the process lacks privileges to open a raw route socket, or resource limits (EMFILE/ENFILE) are hit.

Common situations: Nebula started without root/admin privileges on macOS; hard process file-descriptor limits exhausted in environments running many sockets; restricted macOS sandbox blocking AF_ROUTE sockets.

Related errors

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

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