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

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

error configuring interface: %s

Error message

error configuring interface: %s

What it means

Windows Create() failed at configurer.ConfigureInterface, the same WGUSPConfigurer path as on unix: wgtypes.ParseKey on the private key, then device.IpcSet applying private_key/listen_port/fwmark to the userspace wireguard device. The configurer is created via NewUSPConfigurer (with UAPI listener, whose startup failure is only logged), so this wrap comes from key parsing or IpcSet. Both device and configurer are closed on failure.

Source

Thrown at client/iface/device/device_windows.go:117

			nbiface6.NLMTU = uint32(t.mtu)
			if err := nbiface6.Set(); err != nil {
				log.Warnf("failed to set IPv6 interface MTU, continuing v4-only: %v", err)
				t.address.ClearIPv6()
			}
		}
	}
	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) {
	err := t.device.Up()
	if err != nil {
		return nil, err
	}

	udpMux, err := t.iceBind.GetICEMux()
	if err != nil {
		return nil, err
	}
	t.udpMux = udpMux
	log.Debugf("device is ready to use: %s", t.name)
	return udpMux, nil
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

Pre-validate the private key with wgtypes.ParseKey before Create()
Ensure the wg port is free (netstat -ano) and only one instance runs
Enable debug logs to see the exact IpcSet error inside this wrap
Re-register the agent if the key is corrupted

Defensive patterns

Strategy: validation

Validate before calling

if _, err := wgtypes.ParseKey(privateKey); err != nil {
    return fmt.Errorf("invalid private key: %w", err)
}
if port < 1 || port > 65535 {
    return fmt.Errorf("invalid listen port %d", port)
}

Try / catch

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

Prevention

Validate keys when loading persisted state
Keep one agent instance per port
Surface debug logs so the IpcSet cause is captured

When it happens

Trigger: Invalid private key format; IpcSet rejecting listen_port or fwmark; the ICE bind unable to open the listen port; IpcSet against a concurrently closed device.

Common situations: Corrupted persisted key, port conflicts with another VPN client or agent instance, invalid fwmark under advanced routing.

Related errors

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