netbirdio/netbird · error

error assigning ip: %s

Error message

error assigning ip: %s

What it means

Userspace-mode Create() failed while assigning the overlay IP to the freshly created tun interface (assignAddr routes through wgLink.assignAddr). On linux this lists/deletes existing addresses, adds the new prefix and brings the link up via netlink; on freebsd it shells out to ifconfig. The wrapped inner error names the failing step ('list addr', 'del addr', 'add addr <prefix>', 'link setup' on linux; 'link by name', 'assign addr', 'up' on freebsd).

Source

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

	log.Info("create tun interface")
	tunIface, err := tun.CreateTUN(t.name, int(t.mtu))
	if err != nil {
		log.Debugf("failed to create tun interface (%s, %d): %s", t.name, int(t.mtu), err)
		return nil, fmt.Errorf("error creating tun device: %s", err)
	}
	t.filteredDevice = newDeviceFilter(tunIface)

	// 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] "),
	)

	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) {
	if t.device == nil {
		return nil, fmt.Errorf("device is not ready yet")
	}

	err := t.device.Up()

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Read the wrapped step name to identify exactly which operation failed
2. Run with CAP_NET_ADMIN and confirm the tun interface still exists at that moment
3. Remove leftover interfaces from previous runs before starting the agent
4. Verify the overlay IP/prefix received from management parses as a valid netip.Prefix

// confirm the interface still exists before starting
if _, err := netlink.LinkByName(ifaceName); err != nil {
    return fmt.Errorf("interface %s not present: %w", ifaceName, err)
}

if _, err := dev.Create(); err != nil {
    if strings.Contains(err.Error(), "error assigning ip") {
        if errors.Is(err, syscall.EPERM) {
            // missing CAP_NET_ADMIN
        }
        // inspect inner step: list addr / del addr / add addr / link setup
    }
    return err
}

When it happens

Trigger: netlink.AddrList/AddrDel/AddrAdd/LinkSetUp failing with EPERM without CAP_NET_ADMIN, the interface being deleted concurrently, or an invalid address prefix; IPv6 add failure is soft (warn plus ClearIPv6) but IPv4 add or link setup is fatal.

Common situations: NetworkManager/systemd-networkd racing the agent, running without privileges, a stale half-configured interface left by a crashed run.

Related errors

• create ipset: %w
• delete ip from ipset: %w
• create ipset %s: %w
• add IP to ipset %s: %w
• delete IP from ipset %s: %w

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