netbirdio/netbird · critical

error creating tun device: %s

Error message

error creating tun device: %s

What it means

Windows Create() failed at tun.CreateTUNWithRequestedGUID, which creates the wintun adapter with the requested name, GUID and MTU via the wintun driver (wintun.dll loaded by wireguard-go's tun package). The GUID itself was already resolved by getGUID earlier; failing there returns a different error, so this wrap is specifically adapter creation.

Source

Thrown at client/iface/device/device_windows.go:65

func getGUID() (windows.GUID, error) {
	guidString := defaultWindowsGUIDSTring
	if CustomWindowsGUIDString != "" {
		guidString = CustomWindowsGUIDString
	}
	return windows.GUIDFromString(guidString)
}

func (t *TunDevice) Create() (WGConfigurer, error) {
	guid, err := getGUID()
	if err != nil {
		log.Errorf("failed to get GUID: %s", err)
		return nil, err
	}
	log.Info("create tun interface")
	tunDevice, err := tun.CreateTUNWithRequestedGUID(t.name, &guid, int(t.mtu))
	if err != nil {
		return nil, fmt.Errorf("error creating tun device: %s", err)
	}
	t.nativeTunDevice = tunDevice.(*tun.NativeTun)
	t.filteredDevice = newDeviceFilter(tunDevice)

	// We need to create a wireguard-go device and listen to configuration requests
	t.device = device.NewDevice(
		t.filteredDevice,
		t.iceBind,
		device.NewLogger(wgLogLevel(), "[netbird] "),
	)

	luid := winipcfg.LUID(t.nativeTunDevice.LUID())

	nbiface, err := luid.IPInterface(windows.AF_INET)
	if err != nil {
		t.device.Close()
		return nil, fmt.Errorf("got error when getting ip interface %s", err)
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Run the NetBird Windows service as LocalSystem/administrator
2. Reinstall the client so the bundled wintun.dll is restored (AV may have removed it)
3. Remove stale adapters with the same name and retry creation
4. Confirm the Windows version is supported by the bundled wintun release

var token windows.Token
if err := windows.OpenProcessToken(windows.CurrentProcess(), windows.TOKEN_QUERY, &token); err == nil {
    if elev, _ := token.IsElevated(); !elev {
        log.Warn("wintun adapter creation requires an elevated service")
    }
}

if _, err := dev.Create(); err != nil {
    if strings.Contains(err.Error(), "error creating tun device") {
        // driver problem: verify wintun.dll presence, AV exclusions, and elevation; reinstall client
    }
    return err
}

When it happens

Trigger: wintun.dll missing or wrong architecture, unsupported Windows build, adapter name conflict, driver resource exhaustion, daemon not running elevated.

Common situations: Fresh systems without the driver, antivirus quarantining wintun.dll, wireguard-go/wintun version mismatches after upgrades, running the daemon as a non-elevated user.

Related errors

• got error when getting ip interface %s
• interface has not been initialized yet
• failed to remove interface %s: %w - %s
• self deletion is not allowed
• only integration service user can delete this user

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