netbirdio/netbird · error

link by name: %w

Error message

link by name: %w

What it means

Returned by the FreeBSD link manager's isExist() when LinkByName() fails with any error other than ErrDoesNotExist. LinkByName shells out to `ifconfig <name>` and maps an output containing 'does not exist' to ErrDoesNotExist, which is handled as a normal negative result; every other failure is wrapped here. It means the existence check itself broke (helper missing, output unparseable, permission denied), not that the interface is absent.

Source

Thrown at client/iface/freebsd/link.go:121

	return l.setAddr(ip, netmask)
}

func (l *Link) Up() error {
	return l.up(l.name)
}

func (l *Link) Down() error {
	return l.down(l.name)
}

func (l *Link) isExist() (bool, error) {
	_, err := LinkByName(l.name)
	if errors.Is(err, ErrDoesNotExist) {
		return false, nil
	}

	if err != nil {
		return false, fmt.Errorf("link by name: %w", err)
	}

	return true, nil
}

func (l *Link) create(groupName string) (string, error) {
	cmd := exec.Command("ifconfig", groupName, "create")

	output, err := cmd.CombinedOutput()
	if err != nil {
		log.Debugf("ifconfig out: %s", output)

		return "", fmt.Errorf("create %s interface: %w", groupName, err)
	}

	interfaceName, err := parseIFName(output)
	if err != nil {
		return "", fmt.Errorf("parse interface name: %w", err)

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Verify ifconfig is reachable by the daemon: check the service PATH includes /usr/sbin and run `which ifconfig`
2. Run the agent as root so ifconfig queries cannot fail on privileges
3. Reproduce manually with `ifconfig <ifaceName>` and confirm standard English output
4. Set LC_ALL=C in the daemon environment so output parsing is stable
5. Restart the agent so Recreate() retries with a fixed environment

Example fix

# before (service with stripped PATH)
[Service]
Environment="PATH=/bin"

# after
[Service]
Environment="PATH=/sbin:/usr/sbin:/bin:/usr/bin"

if _, err := exec.LookPath("ifconfig"); err != nil {
    return fmt.Errorf("ifconfig not in daemon PATH: %w", err)
}
if _, err := freebsd.LinkByName("lo0"); err != nil {
    return fmt.Errorf("ifconfig not usable in this environment: %w", err)
}

ok, err := link.Recreate()
if err != nil {
    if strings.Contains(err.Error(), "link by name") {
        // environment failure (PATH/privileges/output format), not a missing interface
        return fmt.Errorf("fix ifconfig availability: %w", err)
    }
    return err
}

When it happens

Trigger: Calling Link.Recreate()/Add()/Del() (they start with isExist) when `ifconfig <name>` exits non-zero without 'does not exist' in its output: ifconfig missing from the daemon PATH (exec error with empty output), unprivileged run, or ifconfig output that parseIfconfigOutput cannot parse (no ': flags' line, bad MTU field).

Common situations: Agent in a jail, container, or minimal FreeBSD install without /usr/sbin in PATH; a service manager that strips the root PATH; localized ifconfig messages that no longer contain the literal 'does not exist'; stale interface name from a crashed run.

Related errors

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

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