netbirdio/netbird · error

link by name: %w

Error message

link by name: %w

What it means

At the start of freebsd wgLink.assignAddr, freebsd.LinkByName(l.name) runs `ifconfig <name>` to obtain the interface object; failure is wrapped as 'link by name'. LinkByName itself can fail on a missing interface (parsed ifconfig output), unparseable output, a name mismatch (ErrNameDoesNotMatch), or a generic command failure. This is the IPv4 configuration path, so it is fatal.

Source

Thrown at client/iface/device/wg_link_freebsd.go:64

	if err := l.link.SetMTU(mtu); err != nil {
		return fmt.Errorf("set mtu: %w", err)
	}

	return nil
}

func (l *wgLink) up() error {
	if err := l.link.Up(); err != nil {
		return fmt.Errorf("up: %w", err)
	}

	return nil
}

func (l *wgLink) assignAddr(address *wgaddr.Address) error {
	link, err := freebsd.LinkByName(l.name)
	if err != nil {
		return fmt.Errorf("link by name: %w", err)
	}

	prefixLen := address.Network.Bits()
	maskBits := uint32(0xffffffff) << (32 - prefixLen)
	mask := fmt.Sprintf("0x%08x", maskBits)

	log.Infof("assign addr %s mask %s to %s interface", address.IP, mask, l.name)

	if err := link.AssignAddr(address.IP.String(), mask); err != nil {
		return fmt.Errorf("assign addr: %w", err)
	}

	if address.HasIPv6() {
		log.Infof("assign IPv6 addr %s to %s interface", address.IPv6String(), l.name)
		cmd := exec.Command("ifconfig", l.name, "inet6", address.IPv6String())
		if out, err := cmd.CombinedOutput(); err != nil {
			log.Warnf("failed to assign IPv6 address %s to %s, continuing v4-only: %s: %v", address.IPv6String(), l.name, string(out), err)
			address.ClearIPv6()

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Run `ifconfig <name>` manually right before starting the agent to confirm the interface exists
2. Check earlier log lines for a failed create step that made the interface absent
3. Ensure stable interface naming and adequate privileges
4. Verify ifconfig is present in PATH for the daemon

// fail early if the interface is not visible
if _, err := freebsd.LinkByName(ifaceName); err != nil {
    return fmt.Errorf("interface %s not found before assign: %w", ifaceName, err)
}

if err := link.assignAddr(addr); err != nil {
    if errors.Is(err, freebsd.ErrDoesNotExist) {
        // interface absent: recreate it and retry assignment
    }
    return err
}

When it happens

Trigger: The wg interface does not exist at assignment time (creation failed earlier or the interface was destroyed), ifconfig missing from PATH, or ifconfig output that cannot be parsed.

Common situations: Race between interface creation and address assignment; leftover name conflicts; running inside a jail where the interface is not visible.

Related errors

• up: %w
• assign addr: %w
• link by name: %w
• change name %q -> %q: %w
• set interface addr: %w

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