netbirdio/netbird · error

install service: %w

Error message

install service: %w

What it means

kardianos/service Install() failed while registering the NetBird daemon with the system service manager (systemd unit, launchd plist, or Windows SCM). The %w chain keeps the manager-specific reason, which on Linux usually includes systemctl output.

Source

Thrown at client/cmd/service_installer.go:156

		if err := loadAndApplyServiceParams(cmd); err != nil {
			cmd.PrintErrf("Warning: failed to load saved service params: %v\n", err)
		}

		svcConfig, err := createServiceConfigForInstall()
		if err != nil {
			return err
		}

		ctx, cancel := context.WithCancel(cmd.Context())
		defer cancel()

		s, err := newSVC(newProgram(ctx, cancel), svcConfig)
		if err != nil {
			return err
		}

		if err := s.Install(); err != nil {
			return fmt.Errorf("install service: %w", err)
		}

		if err := saveServiceParams(currentServiceParams()); err != nil {
			cmd.PrintErrf("Warning: failed to save service params: %v\n", err)
		}

		cmd.Println("NetBird service has been installed")
		return nil
	},
}

var uninstallCmd = &cobra.Command{
	Use:   "uninstall",
	Short: "uninstalls NetBird service from system",
	RunE: func(cmd *cobra.Command, args []string) error {
		if err := setupServiceCommand(cmd); err != nil {
			return err
		}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Re-run with elevation: sudo netbird service install (or an elevated PowerShell on Windows)
2. Remove the previous registration first: sudo netbird service uninstall, or inspect the leftover unit with systemctl status netbird
3. If in a container, run with systemd as PID 1 or install on the host instead
4. Read the wrapped manager error for the exact systemctl/SCM message before retrying

if os.Geteuid() != 0 {
	return errors.New("netbird service install requires root/admin")
}
if _, err := os.Stat(filepath.Join("/etc/systemd/system", serviceName+".service")); err == nil {
	return errors.New("service already installed; run netbird service uninstall first")
}

if err := s.Install(); err != nil {
	return fmt.Errorf("install service: %w", err)
}
// Read the manager-specific text under the wrap; privilege failures never succeed on retry without elevation.

When it happens

Trigger: Running `netbird service install` without root/admin; a netbird unit or Windows service with the same --service name already exists; systemd not reachable (container, chroot); installing into a read-only /etc or /Library/LaunchDaemons.

Common situations: Second install without an intervening uninstall; running install inside docker/podman where systemd is not PID 1; Windows UAC elevation declined so the SCM refuses registration.

Related errors

• uninstall service: %w
• uninstall existing service: %w
• install service with new config: %w
• create service config: %w
• start service after reconfigure: %w

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