netbirdio/netbird · error

named pipes are only supported on Windows

Error message

named pipes are only supported on Windows

What it means

The daemon was told to serve on a Windows named pipe, but this build is the non-Windows stub of listenNamedPipe (//go:build !windows), which unconditionally returns an error. Nothing is bound; it is a platform misuse caught at address parsing time.

Source

Thrown at client/cmd/service_pipe_other.go:13

//go:build !windows

package cmd

import (
	"fmt"
	"net"
)

// listenNamedPipe is Windows-only: no other platform serves the daemon on a
// named pipe.
func listenNamedPipe(string) (net.Listener, string, error) {
	return nil, "", fmt.Errorf("named pipes are only supported on Windows")
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Use a platform-appropriate scheme: unix:///var/run/netbird.sock on Linux/macOS, or tcp://127.0.0.1:port where a kernel socket is not possible
2. Remove the npipe value from shared config or service.json
3. Reinstall the service with the corrected flag so the bad address is not persisted

Example fix

# before (on linux)
netbird service run --daemon-addr npipe://netbird
# after
netbird service run --daemon-addr unix:///var/run/netbird.sock

if strings.HasPrefix(daemonAddr, "npipe://") && runtime.GOOS != "windows" {
	return fmt.Errorf("npipe:// daemon address %q requires windows; use unix:// or tcp://", daemonAddr)
}

func supportsNamedPipe() bool {
	return runtime.GOOS == "windows"
}

if _, _, err := listenNamedPipe(name); err != nil {
	if runtime.GOOS != "windows" {
		// permanent condition: switch the address scheme instead of retrying
		return fallbackToUnixOrTCP()
	}
	return err
}

When it happens

Trigger: Passing --daemon-addr npipe://netbird (or a config/saved service params carrying an npipe value) to `netbird service run` on Linux/macOS/FreeBSD.

Common situations: Copying a Windows --daemon-addr into a Linux systemd unit; one shared config file used across platforms.

Related errors

• %s: %w
• address must be in [unix|tcp|npipe]://[path|host:port|name]
• unsupported daemon address protocol: %v
• create SSH proxy: %w
• management client is not initialised

AI-assisted analysis of netbirdio/netbird@93e97f4bf1 (2026-08-16). Data as JSON: /api/errors/0ca21fb1f0487f57. Report an issue: GitHub.