What causes "error assigning ip: %s" in netbirdio/netbird?

Read the wrapped error to identify the failing winipcfg call

error assigning ip: %s

Error message

error assigning ip: %s

What it means

Windows Create() failed at assignAddr, which programs the adapter's IP address, mask and associated routes through winipcfg after the MTU steps. Any failure inside that address/route configuration closes the device and surfaces under this wrap. The inner error identifies the failing winipcfg operation.

Source

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

	}

	if t.address.HasIPv6() {
		nbiface6, err := luid.IPInterface(windows.AF_INET6)
		if err != nil {
			log.Warnf("failed to get IPv6 interface for MTU, continuing v4-only: %v", err)
			t.address.ClearIPv6()
		} else {
			nbiface6.NLMTU = uint32(t.mtu)
			if err := nbiface6.Set(); err != nil {
				log.Warnf("failed to set IPv6 interface MTU, continuing v4-only: %v", err)
				t.address.ClearIPv6()
			}
		}
	}
	err = t.assignAddr()
	if err != nil {
		t.device.Close()
		return nil, fmt.Errorf("error assigning ip: %s", err)
	}

	t.configurer = configurer.NewUSPConfigurer(t.device, t.name, t.iceBind.ActivityRecorder())
	err = t.configurer.ConfigureInterface(t.key, t.port)
	if err != nil {
		t.device.Close()
		t.configurer.Close()
		return nil, fmt.Errorf("error configuring interface: %s", err)
	}
	return t.configurer, nil
}

func (t *TunDevice) Up() (*udpmux.UniversalUDPMuxDefault, error) {
	err := t.device.Up()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Read the wrapped error to identify the failing winipcfg call
Check that the assigned NetBird IP range does not overlap the local LAN
Remove the stale adapter so the agent recreates it cleanly
Ensure the service is running elevated

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check the overlay range does not collide with an existing adapter
addrs, _ := winipcfg.GetUnicastIPAddresses(windows.AF_INET, nil)
for _, a := range addrs {
    if a.Address.IP().Is4() && overlayRange.Contains(a.Address.IP()) {
        log.Warnf("address %s already present on another interface", a.Address.IP())
    }
}

Try / catch

if _, err := dev.Create(); err != nil {
    if strings.Contains(err.Error(), "error assigning ip") {
        // read the wrapped winipcfg error; check overlaps and stale adapters
    }
    return err
}

Prevention

Choose overlay ranges that cannot overlap the LAN
Remove stale adapters before reconnecting
Run the service elevated so winipcfg calls succeed

When it happens

Trigger: The overlay address already assigned to another adapter, an invalid address/prefix from management, winipcfg API failure, or the adapter being removed mid-configuration.

Common situations: Overlay network range overlapping the LAN, stale configuration from a previous run, third-party firewall blocking interface configuration.

Related errors

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