netbirdio/netbird · error

%s init: %w

Error message

%s init: %w

What it means

Init-time failure of one of the four subsystems (router, acl manager, v6 router, v6 acl manager) inside Manager.Init via initChains. The message prefixes the failing step name ('router init:', 'acl manager init:', 'v6 router init:', 'v6 acl manager init:') to the underlying cause, which is almost always an iptables operation failing in cleanChains, createDefaultChains, or createContainers. The library has already rolled back every previously initialized step in reverse order (Reset, failures logged as 'rollback ...'), so no half-built chains from this run survive.

Source

Thrown at client/firewall/iptables/manager_linux.go:172

		{"router", m.router.init, m.router},
		{"acl manager", m.aclMgr.init, m.aclMgr},
	}
	if m.hasIPv6() {
		steps = append(steps,
			initStep{"v6 router", m.router6.init, m.router6},
			initStep{"v6 acl manager", m.aclMgr6.init, m.aclMgr6},
		)
	}

	var initialized []initStep
	for _, s := range steps {
		if err := s.init(stateManager); err != nil {
			for i := len(initialized) - 1; i >= 0; i-- {
				if rerr := initialized[i].mgr.Reset(); rerr != nil {
					log.Warnf("rollback %s: %v", initialized[i].name, rerr)
				}
			}
			return fmt.Errorf("%s init: %w", s.name, err)
		}
		initialized = append(initialized, s)
	}
	return nil
}

// AddPeerFiltering adds a rule to the firewall
//
// Comment will be ignored because some system this feature is not supported
func (m *Manager) AddPeerFiltering(
	id []byte,
	ip net.IP,
	proto firewall.Protocol,
	sPort *firewall.Port,
	dPort *firewall.Port,
	action firewall.Action,
	ipsetName string,
) ([]firewall.Rule, error) {

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Run the daemon as root (the agent is a privileged daemon by design)
2. Install iptables and ip6tables and verify manually as root: iptables -L and ip6tables -L
3. On modern hosts prefer the nftables backend the factory normally selects via check() in client/firewall/create_linux.go
4. For userspace-bind setups, set NB_FORCE_USERSPACE_FIREWALL to skip the native firewall entirely
5. Check daemon logs for the preceding 'rollback' warnings to confirm cleanup ran

func canInitIptables() error {
    if os.Geteuid() != 0 {
        return fmt.Errorf("agent must run as root to program iptables")
    }
    for _, bin := range []string{"iptables", "ip6tables"} {
        if _, err := exec.LookPath(bin); err != nil {
            return fmt.Errorf("%s not installed", bin)
        }
    }
    return nil
}

if err := mgr.Init(stateManager); err != nil {
    log.Errorf("firewall init failed (rollback already done by library): %v", err)
    // choose a fallback: nftables backend, userspace firewall, or abort
    return fmt.Errorf("init firewall: %w", err)
}

When it happens

Trigger: Calling Manager.Init(stateManager) when: the iptables/ip6tables binary is missing or not executable; the process lacks root/CAP_NET_ADMIN; List/Append on the filter or nat table errors; or the v6 steps run on a host without usable ip6tables even though the interface address has v6.

Common situations: Minimal or distroless containers without the iptables package; running the agent unprivileged; nftables-only hosts where the iptables-nft compatibility layer is absent; sandboxes without /proc/net; the v6 half failing because ip6tables lives in a separate distro package (e.g. iptables vs iptables-ipv6 splits).

Related errors

• failed to check rule: %w
• create v6 acl manager: %w
• add IP to ipset: %w
• create ipset: %w
• rule already exists

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