hashicorp/nomad · error

failed to initialize table forwarding rules: %v

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.

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)

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: %v
• invalid ';' character in CNI arg value %q
• network namespace already exists but was misconfigured
• no CNI network config found
• No path to region

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