netbirdio/netbird · warning

clean jump rules: %w

Error message

clean jump rules: %w

What it means

Returned by router.cleanUpDefaultForwardRules when cleanJumpRules fails. cleanJumpRules deletes the jump rules the router installed from built-in chains (POSTROUTING/PREROUTING nat, FORWARD mangle for MSS clamp) using specs stored under well-known keys in r.rules, returning early on the first DeleteIfExists failure or an unknown key. init() only logs this error; Reset() propagates it inside a multierror.

Source

Thrown at client/firewall/iptables/router_linux.go:398

	}

	if err := r.ipsetCounter.Flush(); err != nil {
		merr = multierror.Append(merr, err)
	}

	if err := r.cleanupDataPlaneMark(); err != nil {
		merr = multierror.Append(merr, err)
	}

	r.rules = make(map[string][]string)
	r.updateState()

	return nberrors.FormatErrorOrNil(merr)
}

func (r *router) cleanUpDefaultForwardRules() error {
	if err := r.cleanJumpRules(); err != nil {
		return fmt.Errorf("clean jump rules: %w", err)
	}

	log.Debug("flushing routing related tables")

	// Remove jump rules from built-in chains before deleting custom chains,
	// otherwise the chain deletion fails with "device or resource busy".
	if ok, err := r.iptablesClient.ChainExists(tableNat, chainNATOutput); err != nil {
		return fmt.Errorf("check chain %s: %w", chainNATOutput, err)
	} else if ok {
		jumpRule := []string{"-j", chainNATOutput}
		if err := r.iptablesClient.Delete(tableNat, "OUTPUT", jumpRule...); err != nil {
			log.Debugf("clean OUTPUT jump rule: %v", err)
		}
	}

	for _, chainInfo := range []struct {
		chain string
		table string

View on GitHub (pinned to 93e97f4bf1)

Solutions

1. Retry: init proceeds to recreate containers anyway, and next run repeats the cleanup
2. Manually verify built-in chains: sudo iptables -t nat -S POSTROUTING; -t mangle -S PREROUTING; -t mangle -S FORWARD
3. Remove stale NETBIRD jump rules by hand if the sweep keeps failing
4. Avoid restarting other firewall services exactly while netbird starts/stops

if err := r.cleanUpDefaultForwardRules(); err != nil {
	log.Errorf("failed to clean up rules from FORWARD chain: %s", err) // init already tolerates this
}

When it happens

Trigger: Agent startup (init) or Reset()/teardown, for jump-rule keys present in r.rules (restored from persisted state or created this session). Fails on iptables invocation errors: xtables lock contention, backend switch, or the built-in chain having been replaced by another tool.

Common situations: firewalld/ufw restarts replacing base chains while netbird tears down; crash-recovery where persisted r.rules reference specs that no longer parse under the active iptables backend.

Related errors

• destroy set %s: %w
• remove nat rule: %w
• remove inverse nat rule: %w
• remove legacy routing rule: %w
• remove legacy forwarding rule %s -> %s: %v

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