hashicorp/nomad · error

failed to initialize table forwarding rules

Error message

failed to initialize table forwarding rules: %v

What it means

bridgeNetworkConfigurator.Setup installs iptables forwarding rules (via ensureForwardingRules) before invoking CNI. If that initialization fails, Setup returns this error wrapping the cause. It prevents allocations from starting on a bridge whose host forwarding rules could not be created, since traffic would be dropped or unsafe.

Solutions

1. Install iptables on the host and ensure the Nomad agent runs with sufficient privileges (root or CAP_NET_ADMIN).
2. Check the wrapped error for the iptables exec output and fix the underlying rule-creation failure.
3. If running Nomad in a container, run with --cap-add=NET_ADMIN -v /lib/modules:/lib/modules.
4. Ensure iptables-legacy/iptables-nft match the host firewall backend.
5. Verify no security module (SELinux/AppArmor) blocks iptables for the agent.

Example fix

# before (error on host)
$ iptables --version
bash: iptables: command not found
# after
$ apt-get install -y iptables

// node pre-flight before starting the Nomad agent
sh -c 'command -v iptables && iptables -L -n >/dev/null' || echo 'iptables unavailable'

alloc, err := cfg.Setup(ctx, alloc, spec, created)
if err != nil && strings.Contains(err.Error(), "forwarding rules") {
  // surface iptables diagnostic: run `iptables -L` and check CAP_NET_ADMIN
  return fmt.Errorf("bridge setup blocked: %w", err)
}

When it happens

Trigger: ensureForwardingRules() fails inside bridgeNetworkConfigurator.Setup: iptables binary missing, insufficient permissions (not root / missing CAP_NET_ADMIN), iptables backend (nft vs legacy) problems, or IPTables constructor error.

Common situations: Running the Nomad agent in a container without NET_ADMIN; host without iptables installed; hosts using nftables-only with no iptables-nft shim; selinux denials blocking iptables exec.

Related errors

• failed to create network for alloc
• invalid ';' character in CNI arg value
• cannot use address_mode="alloc": no allocation network…
• cni not initialized
• Connect only supported with exactly 1 network

AI-assisted analysis of hashicorp/nomad@482b49bf1a (2026-09-04). Data as JSON: /api/errors/a71aeaa0c95b3905. Report an issue: GitHub.

Appendix: source

Thrown at client/allocrunner/networking_bridge_linux.go:125

		}
	}

	ipt, err := b.newIPTables(structs.NodeNetworkAF_IPv4)
	if err != nil {
		return err
	}

	if err = ensureChainRule(ipt, b.bridgeName, b.allocSubnetIPv4); err != nil {
		return err
	}

	return nil
}

// Setup calls the CNI plugins with the add action
func (b *bridgeNetworkConfigurator) Setup(ctx context.Context, alloc *structs.Allocation, spec *drivers.NetworkIsolationSpec, created bool) (*structs.AllocNetworkStatus, error) {
	if err := b.ensureForwardingRules(); err != nil {
		return nil, fmt.Errorf("failed to initialize table forwarding rules: %v", err)
	}

	return b.cni.Setup(ctx, alloc, spec, created)
}

// Teardown calls the CNI plugins with the delete action
func (b *bridgeNetworkConfigurator) Teardown(ctx context.Context, alloc *structs.Allocation, spec *drivers.NetworkIsolationSpec) error {
	return b.cni.Teardown(ctx, alloc, spec)
}

func buildNomadBridgeNetConfig(b bridgeNetworkConfigurator, withConsulCNI bool) ([]byte, error) {
	conf := cni.NewNomadBridgeConflist(cni.NomadBridgeConfig{
		BridgeName:     b.bridgeName,
		AdminChainName: cniAdminChainName,
		IPv4Subnet:     b.allocSubnetIPv4,
		IPv6Subnet:     b.allocSubnetIPv6,
		HairpinMode:    b.hairpinMode,
		ConsulCNI:      withConsulCNI,

View on GitHub (pinned to 482b49bf1a)