netbirdio/netbird · warning

invalid IP or network interface name not found

Error message

invalid IP or network interface name not found

What it means

validateElement is the leaf classifier for --external-ip-map values: it returns ipInputType for a valid IP, else queries net.Interfaces() for a matching interface name. When the value is not a valid IP and no interface with that name exists, this 'invalid IP or network interface name not found' error is returned (with interfaceInputType as a placeholder type the caller discards).

Source

Thrown at client/cmd/up.go:792

	}

	return fmt.Errorf("invalid interface name %s. Please use the prefix utun followed by a number on MacOS. e.g., utun1 or utun199", name)
}

func validateElement(element string) (int, error) {
	if isValidIP(element) {
		return ipInputType, nil
	}
	validIface, err := isValidInterface(element)
	if err != nil {
		return invalidInputType, fmt.Errorf("unable to validate the network interface name, error: %s", err)
	}

	if validIface {
		return interfaceInputType, nil
	}

	return interfaceInputType, fmt.Errorf("invalid IP or network interface name not found")
}

func isValidIP(ip string) bool {
	return net.ParseIP(ip) != nil
}

func isValidInterface(name string) (bool, error) {
	netInterfaces, err := net.Interfaces()
	if err != nil {
		return false, err
	}
	for _, iface := range netInterfaces {
		if iface.Name == name {
			return true, nil
		}
	}
	return false, nil
}

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Check the exact string for typos and stray whitespace
2. Confirm the interface exists locally (`ip link` / `ifconfig`) or replace it with an IP literal
3. Fix the malformed IP

Example fix

# before
netbird up --external-ip-map "192.0.2.10/eth0 "
# after
netbird up --external-ip-map "192.0.2.10/eth0"

func isIPOrExistingInterface(v string) bool {
	if net.ParseIP(v) != nil {
		return true
	}
	ifaces, err := net.Interfaces()
	if err != nil {
		return false
	}
	for _, i := range ifaces {
		if i.Name == v {
			return true
		}
	}
	return false
}

When it happens

Trigger: A sub-element like "10.0.0.x" (malformed IP) or "eth0 " (whitespace-padded interface name) or an interface that exists on another host but not this one.

Common situations: Whitespace from quoted scripts, stale interface names after hardware/NIC renaming, or values written for a different machine in a shared config.

Related errors

• %s is not a valid input for %s. it should be formatted as "I
• empty string is not a valid input for %s
• %s is not a valid input for %s. it should be formatted as "S
• %s is not a valid input for %s. it should be an IP string or
• %s is not a valid input for %s. it should not contain two in

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