hashicorp/nomad · error

failed to detect iptables

Error message

failed to detect iptables: %w

What it means

During Teardown's best-effort manual iptables cleanup, constructing the IPTables handle (newIPTables) failed - iptables binary missing or not executable - so leftover rules for the alloc cannot be purged automatically.

Solutions

  1. Install iptables on the client host and ensure it is in PATH
  2. Verify execute permissions on iptables/ip6tables binaries
  3. Manually remove leftover CNI-* chains/rules for the alloc ID
Defensive patterns

Strategy: fallback

When it happens

Trigger: Thrown at client/allocrunner/networking_cni.go:612 when the library encounters an invalid state.

Common situations: See trigger scenarios.


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

Appendix: source

Thrown at client/allocrunner/networking_cni.go:612

	portMap := getPortMapping(alloc, c.ignorePortMappingHostIP)

	if err := c.cni.Remove(ctx, alloc.ID, spec.Path, cni.WithCapabilityPortMap(portMap.ports)); err != nil {
		c.logger.Warn("error from cni.Remove; attempting manual iptables cleanup", "err", err)

		// best effort cleanup ipv6
		ipt, iptErr := c.newIPTables(structs.NodeNetworkAF_IPv6)
		if iptErr != nil {
			c.logger.Debug("failed to detect ip6tables", "error", iptErr)
		} else {
			if err := c.forceCleanup(ipt, alloc.ID); err != nil {
				c.logger.Warn("failed to cleanup iptables", "error", err)
			}
		}

		// create a real handle to iptables
		ipt, iptErr = c.newIPTables(structs.NodeNetworkAF_IPv4)
		if iptErr != nil {
			return fmt.Errorf("failed to detect iptables: %w", iptErr)
		}
		// most likely the pause container was removed from underneath nomad
		return c.forceCleanup(ipt, alloc.ID)
	}

	return nil
}

var (
	// ipRuleRe is used to parse a postrouting iptables rule created by nomad, e.g.
	//   -A POSTROUTING -s 172.26.64.191/32 -m comment --comment "name: \"nomad\" id: \"6b235529-8111-4bbe-520b-d639b1d2a94e\"" -j CNI-50e58ea77dc52e0c731e3799
	ipRuleRe = regexp.MustCompile(`-A POSTROUTING -s (\S+) -m comment --comment "name: \\"nomad\\" id: \\"([[:xdigit:]-]+)\\"" -j (CNI-[[:xdigit:]]+)`)
)

// forceCleanup is the backup plan for removing the iptables rule and chain associated with
// an allocation that was using bridge networking. The cni library refuses to handle a
// dirty state - e.g. the pause container is removed out of band, and so we must cleanup
// iptables ourselves to avoid leaking rules.

View on GitHub (pinned to 482b49bf1a)