What causes "failed to write route.RouteMessage to socket: %w" in slackhq/nebula?

Run nebula as root or with the privileges needed to modify the routing table (the process needs write access to the route socket).

slackhq/nebula · error

failed to write route.RouteMessage to socket: %w

Error message

failed to write route.RouteMessage to socket: %w

What it means

addRoute (overlay/tun_freebsd.go:659) writes the marshaled route.RouteMessage (RTM_ADD) to the AF_ROUTE socket with unix.Write. This error wraps any failure of that write, meaning the kernel routing socket rejected the route-add message.

Source

Thrown at overlay/tun_freebsd.go:659

	data, err := route.Marshal()
	if err != nil {
		return fmt.Errorf("failed to create route.RouteMessage: %w", err)
	}

	_, err = unix.Write(sock, data[:])
	if err != nil {
		if errors.Is(err, unix.EEXIST) {
			// Try to do a change
			route.Type = unix.RTM_CHANGE
			data, err = route.Marshal()
			if err != nil {
				return fmt.Errorf("failed to create route.RouteMessage for change: %w", err)
			}
			_, err = unix.Write(sock, data[:])
			return err
		}
		return fmt.Errorf("failed to write route.RouteMessage to socket: %w", err)
	}

	return nil
}

func delRoute(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_DELETE,
		Seq:     1,
	}

View on GitHub (pinned to dd8f660c0a)

Solutions

Run nebula as root or with the privileges needed to modify the routing table (the process needs write access to the route socket).
Inspect the wrapped errno in the message to identify the kernel rejection reason (EPERM, ENETUNREACH, ENOBUFS).
Verify the route/gateway is valid and reachable per the interface configuration.
Retry on transient errors like ENOBUFS; addRoutes is typically invoked at startup or reload.

Example fix

// before (run as unprivileged user)
$ nebula -config config.yml
// after
$ sudo nebula -config config.yml

Defensive patterns

Strategy: try-catch

Validate before calling

// Go: check privileges before attempting route writes
if os.Geteuid() != 0 {
	return errors.New("adding routes requires root or CAP_NET_ADMIN")
}

Try / catch

if _, err := unix.Write(sock, data[:]); err != nil {
	if errors.Is(err, unix.ENOBUFS) {
		// transient: retry with backoff
	} else {
		return fmt.Errorf("failed to write route.RouteMessage to socket: %w", err)
	}
}

Prevention

Run nebula as root or with CAP_NET_ADMIN on FreeBSD.
Retry transient ENOBUFS failures with backoff under route churn.
Log the wrapped errno to distinguish permission vs resource issues.

When it happens

Trigger: unix.Write(sock, data) returns an error when submitting an RTM_ADD message: socket closed, permission denied (non-root), or the kernel rejecting the message (invalid/ambiguous route, ENOBUFS).

Common situations: Running nebula without CAP_NET_ADMIN/root privileges so the route socket write fails with EPERM; kernel rejecting a duplicate or malformed route; resource exhaustion (ENOBUFS) under heavy route churn on busy FreeBSD hosts.

Related errors

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