{"record":{"id":"58f4d2eac74aea9c","repo":"netbirdio/netbird","slug":"error-assigning-ip-s-58f4d2","errorCode":null,"errorMessage":"error assigning ip: %s","messagePattern":"error assigning ip: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/iface/device/device_usp_unix.go","lineNumber":65,"sourceCode":"\tlog.Info(\"create tun interface\")\n\ttunIface, err := tun.CreateTUN(t.name, int(t.mtu))\n\tif err != nil {\n\t\tlog.Debugf(\"failed to create tun interface (%s, %d): %s\", t.name, int(t.mtu), err)\n\t\treturn nil, fmt.Errorf(\"error creating tun device: %s\", err)\n\t}\n\tt.filteredDevice = newDeviceFilter(tunIface)\n\n\t// We need to create a wireguard-go device and listen to configuration requests\n\tt.device = device.NewDevice(\n\t\tt.filteredDevice,\n\t\tt.iceBind,\n\t\tdevice.NewLogger(wgLogLevel(), \"[netbird] \"),\n\t)\n\n\terr = t.assignAddr()\n\tif err != nil {\n\t\tt.device.Close()\n\t\treturn nil, fmt.Errorf(\"error assigning ip: %s\", err)\n\t}\n\n\tt.configurer = configurer.NewUSPConfigurer(t.device, t.name, t.iceBind.ActivityRecorder())\n\terr = t.configurer.ConfigureInterface(t.key, t.port)\n\tif err != nil {\n\t\tt.device.Close()\n\t\tt.configurer.Close()\n\t\treturn nil, fmt.Errorf(\"error configuring interface: %s\", err)\n\t}\n\treturn t.configurer, nil\n}\n\nfunc (t *TunDevice) Up() (*udpmux.UniversalUDPMuxDefault, error) {\n\tif t.device == nil {\n\t\treturn nil, fmt.Errorf(\"device is not ready yet\")\n\t}\n\n\terr := t.device.Up()","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/device/device_usp_unix.go#L47-L83","documentation":"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).","triggerScenarios":"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.","commonSituations":"NetworkManager/systemd-networkd racing the agent, running without privileges, a stale half-configured interface left by a crashed run.","solutions":["Read the wrapped step name to identify exactly which operation failed","Run with CAP_NET_ADMIN and confirm the tun interface still exists at that moment","Remove leftover interfaces from previous runs before starting the agent","Verify the overlay IP/prefix received from management parses as a valid netip.Prefix"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// confirm the interface still exists before starting\nif _, err := netlink.LinkByName(ifaceName); err != nil {\n    return fmt.Errorf(\"interface %s not present: %w\", ifaceName, err)\n}","typeGuard":null,"tryCatchPattern":"if _, err := dev.Create(); err != nil {\n    if strings.Contains(err.Error(), \"error assigning ip\") {\n        if errors.Is(err, syscall.EPERM) {\n            // missing CAP_NET_ADMIN\n        }\n        // inspect inner step: list addr / del addr / add addr / link setup\n    }\n    return err\n}","preventionTips":["Run the agent with CAP_NET_ADMIN so netlink address operations succeed","Clean leftover interfaces from crashed runs before starting","Validate the overlay prefix from management before applying it"],"tags":["netlink","ip-address","linux","freebsd","userspace","go"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}