{"record":{"id":"556a99dd640c1e8e","repo":"netbirdio/netbird","slug":"error-configuring-interface-s-556a99","errorCode":null,"errorMessage":"error configuring interface: %s","messagePattern":"error configuring interface: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"client/iface/device/device_netstack.go","lineNumber":93,"sourceCode":"\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"error creating tun device: %s\", err)\n\t}\n\tt.filteredDevice = newDeviceFilter(tunIface)\n\tt.net = net\n\n\tt.device = device.NewDevice(\n\t\tt.filteredDevice,\n\t\tt.bind,\n\t\tdevice.NewLogger(wgLogLevel(), \"[netbird] \"),\n\t)\n\n\tt.configurer = configurer.NewUSPConfigurerNoUAPI(t.device, t.name, t.bind.ActivityRecorder())\n\terr = t.configurer.ConfigureInterface(t.key, t.port)\n\tif err != nil {\n\t\tif cErr := tunIface.Close(); cErr != nil {\n\t\t\tlog.Debugf(\"failed to close tun device: %v\", cErr)\n\t\t}\n\t\treturn nil, fmt.Errorf(\"error configuring interface: %s\", err)\n\t}\n\n\tlog.Debugf(\"device has been created: %s\", t.name)\n\treturn t.configurer, nil\n}\n\nfunc (t *TunNetstackDevice) 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.bind.GetICEMux()\n\tif err != nil && !errors.Is(err, bind.ErrUDPMUXNotSupported) {","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/netbirdio/netbird/blob/93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c/client/iface/device/device_netstack.go#L75-L111","documentation":"Thrown by TunNetstackDevice.create() in netstack mode, where wireguard-go runs over a gVisor userspace stack with no OS tun device. After the device is constructed, WGUSPConfigurerNoUAPI.ConfigureInterface parses the WireGuard private key with wgtypes.ParseKey and applies private_key/listen_port/fwmark via device.IpcSet. This error wraps any failure of that step; the netstack tun is closed and create() returns nil.","triggerScenarios":"wgtypes.ParseKey rejecting t.key (not a 32-byte base64 key), or device.IpcSet rejecting the listen_port/fwmark value, or running against a device closed concurrently.","commonSituations":"Corrupted or regenerated WireGuard key in agent state, an out-of-range port passed to NewNetstackDevice, calling create() twice or Close() racing Create() in embedded (client/embed) usage.","solutions":["Validate the private key with wgtypes.ParseKey before constructing the device and fail fast with a clear message","Ensure the wg port passed to NewNetstackDevice is within 1-65535 and not already bound by another instance","Enable debug logging to capture the exact ParseKey/IpcSet error text under 'error configuring interface:'","If agent state is corrupted, re-register to generate a fresh key"],"exampleFix":"// before\ndev := device.NewNetstackDevice(name, addr, port, key, mtu, bind, listenAddr)\ncfg, err := dev.Create()\n\n// after\nif _, kerr := wgtypes.ParseKey(key); kerr != nil {\n    return fmt.Errorf(\"invalid private key: %w\", kerr)\n}\ndev := device.NewNetstackDevice(name, addr, port, key, mtu, bind, listenAddr)\ncfg, err := dev.Create()","handlingStrategy":"validation","validationCode":"if _, err := wgtypes.ParseKey(privateKey); err != nil {\n    return fmt.Errorf(\"invalid WireGuard private key: %w\", err)\n}\nif port < 1 || port > 65535 {\n    return fmt.Errorf(\"invalid listen port %d\", port)\n}","typeGuard":null,"tryCatchPattern":"cfg, err := dev.Create()\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"error configuring interface\") {\n        // key or IpcSet problem: inspect wrapped cause in logs, do not blind-retry\n    }\n    return err\n}","preventionTips":["Validate WireGuard keys at the boundary where they are loaded from state before any device work","Bound the listen port to 1-65535 at construction time","Never ignore a Create() error; it leaves the device half-built"],"tags":["netstack","wireguard","userspace","configuration","go"],"backgroundTag":null,"analyzedSha":"93e97f4bf1ad715072dcb3fb6cdb1763431b5a9c","analyzedAt":"2026-08-16T03:09:19.136Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}