slackhq/nebula · error

unable to create AF_ROUTE socket

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.

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
• failed to write route.RouteMessage to socket
• failed to write route.RouteMessage to socket
• unable to create AF_ROUTE socket
• unable to create AF_ROUTE socket

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

Appendix: 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)