{"record":{"id":"a758aa4e87bb178b","repo":"netbirdio/netbird","slug":"error-configuring-interface-s-a758aa","errorCode":null,"errorMessage":"error configuring interface: %s","messagePattern":"error configuring interface: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/iface/device/device_usp_unix.go","lineNumber":73,"sourceCode":"\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()\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\tudpMux, err := t.iceBind.GetICEMux()\n\tif err != nil {\n\t\treturn nil, err\n\t}","sourceCodeStart":55,"sourceCodeEnd":91,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/device/device_usp_unix.go#L55-L91","documentation":"Userspace-mode Create() failed at ConfigureInterface: WGUSPConfigurer parses the private key with wgtypes.ParseKey and then applies private_key, listen_port and fwmark to the wireguard-go device through IpcSet. Note NewUSPConfigurer also opens the UAPI socket (/var/run/wireguard/<name>.sock) but that failure is only logged, so this wrap always originates in key parsing or IpcSet. Both the device and configurer are closed on this path.","triggerScenarios":"Invalid base64/length private key in t.key; IpcSet rejecting listen_port or fwmark; the underlying bind failing to open the requested listen port; IpcSet against a concurrently closed device.","commonSituations":"Corrupted key in persisted agent state, a second agent instance conflicting on the same port/socket, a bad fwmark value in advanced-routing setups.","solutions":["Pre-validate the key with wgtypes.ParseKey before calling Create()","Ensure only one agent instance runs and the wg port is free (ss -lun)","Enable debug logs to capture the exact IpcSet error under this wrap","Re-register the agent if the persisted key is corrupted"],"exampleFix":"// before\nerr = t.configurer.ConfigureInterface(t.key, t.port)\n\n// after\nif _, kerr := wgtypes.ParseKey(t.key); kerr != nil {\n    return fmt.Errorf(\"invalid private key: %w\", kerr)\n}\nerr = t.configurer.ConfigureInterface(t.key, t.port)","handlingStrategy":"validation","validationCode":"if _, err := wgtypes.ParseKey(privateKey); err != nil {\n    return fmt.Errorf(\"invalid private key: %w\", err)\n}\nif l, err := net.Listen(\"udp\", fmt.Sprintf(\":%d\", port)); err != nil {\n    return fmt.Errorf(\"listen port %d unavailable: %w\", port, err)\n} else {\n    l.Close()\n}","typeGuard":null,"tryCatchPattern":"if _, err := dev.Create(); err != nil {\n    if strings.Contains(err.Error(), \"error configuring interface\") {\n        // ParseKey or IpcSet failed: fix key/port, then retry create from scratch\n    }\n    return err\n}","preventionTips":["Parse keys once at load time and reject invalid ones early","Ensure a single agent instance per port and UAPI socket","Enable debug logs so the IpcSet cause under the wrap is visible"],"tags":["wireguard","userspace","configuration","ipc","go"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}