What causes "error configuring interface: %s" in netbirdio/netbird?

Pre-validate the key with wgtypes.ParseKey before calling Create()

error configuring interface: %s

Error message

error configuring interface: %s

What it means

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.

Source

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

	// 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()
	if err != nil {
		return nil, err
	}

	udpMux, err := t.iceBind.GetICEMux()
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 93e97f4bf1)

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

Example fix

// before
err = t.configurer.ConfigureInterface(t.key, t.port)

// after
if _, kerr := wgtypes.ParseKey(t.key); kerr != nil {
    return fmt.Errorf("invalid private key: %w", kerr)
}
err = t.configurer.ConfigureInterface(t.key, t.port)

Defensive patterns

Strategy: validation

Validate before calling

if _, err := wgtypes.ParseKey(privateKey); err != nil {
    return fmt.Errorf("invalid private key: %w", err)
}
if l, err := net.Listen("udp", fmt.Sprintf(":%d", port)); err != nil {
    return fmt.Errorf("listen port %d unavailable: %w", port, err)
} else {
    l.Close()
}

Try / catch

if _, err := dev.Create(); err != nil {
    if strings.Contains(err.Error(), "error configuring interface") {
        // ParseKey or IpcSet failed: fix key/port, then retry create from scratch
    }
    return err
}

Prevention

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

When it happens

Trigger: 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.

Common situations: Corrupted key in persisted agent state, a second agent instance conflicting on the same port/socket, a bad fwmark value in advanced-routing setups.

Related errors

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