slackhq/nebula · error

multiple udp listeners not supported on windows

Error message

multiple udp listeners not supported on windows

What it means

This is a hard capability limitation of the library's Windows UDP stack: requesting a multi-device/multi-listener (Settings.Multi) UDP connection on Windows returns this error because multiple UDP listeners are not supported there. The Windows implementation uses RIO sockets, which cannot provide socket-level multi-listener semantics; only the Linux implementation supports Multi.

Source

Thrown at udp/udp_windows.go:18

//go:build !e2e_testing
// +build !e2e_testing

package udp

import (
	"fmt"
	"log/slog"
	"net"
	"syscall"
)

func NewListener(l *slog.Logger, s Settings) (Conn, error) {
	if s.Multi {
		//NOTE: Technically we can support it with RIO but it wouldn't be at the socket level
		// The udp stack would need to be reworked to hide away the implementation differences between
		// Windows and Linux
		return nil, fmt.Errorf("multiple udp listeners not supported on windows")
	}

	var conn Conn
	rc, err := NewRIOListener(l, s.Listen.Addr(), int(s.Listen.Port()))
	if err == nil {
		conn = rc
	} else {
		l.Error("Falling back to standard udp sockets", "error", err)
		conn, err = NewGenericListener(l, s)
		if err != nil {
			return nil, err
		}
	}
	return wrapWithWDFBypass(l, conn), nil
}

func NewListenConfig(multi bool) net.ListenConfig {
	return net.ListenConfig{

View on GitHub (pinned to dd8f660c0a)

Solutions

1. Set listen.multiple to false (or omit it) in the config when running on Windows.
2. If multiple listeners are required, run on Linux where the feature is supported.
3. Restructure the deployment to use a single listener/port on Windows.

Example fix

// before (nebula config, on Windows)
listen:
  port: 4242
  multiple: true
// after
listen:
  port: 4242
  multiple: false

if runtime.GOOS == "windows" && settings.Multi {
	return errors.New("config error: listen.multiple is not supported on windows; disable it or run on linux")
}
conn, err := udp.NewListener(logger, settings)

func multiUnsupportedOnWindows(s udp.Settings) bool { return runtime.GOOS == "windows" && s.Multi }

conn, err := udp.NewListener(logger, settings)
if err != nil && errors.Is(err, errMultiUnsupported) {
	// fall back to single-listener mode automatically
}

When it happens

Trigger: Calling udp.NewListener with Settings{Multi: true} on Windows - e.g. starting nebula with multiple listeners configured (listen.multiple = true) on a Windows host.

Common situations: Users porting a Linux config (where 'multiple: true' works) to Windows; running an instance that must coexist with another on the same port via SO_REUSEADDR-style semantics.

Related errors

• could not initialize winrio
• unknown tun.network_category %q (expected public, private, d
• newTunFromFd not supported in Windows
• generate GUID failed: %w
• bind: %w

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