🚨 Docker Error Guide: 'iptables: No chain/target/match by that name' — Broken Firewall Chains

Overview

Docker programs the host firewall by inserting its own iptables chains (DOCKER, DOCKER-USER, DOCKER-ISOLATION-STAGE-1/2) and rules that NAT and forward container traffic. If those chains are missing — usually because something flushed iptables out from under the daemon — Docker cannot insert a rule and container startup fails:

Error response from daemon: driver failed programming external connectivity on endpoint web (a1b2...): 
iptables failed: iptables --wait -t nat -A DOCKER -p tcp -d 0.0.0.0/0 --dport 8080 -j DNAT ...: 
iptables: No chain/target/match by that name.

Symptoms

• Containers with published ports fail to start after a firewall reload or iptables -F.
• docker run -p ... fails while containers without published ports still start.
• The error appears right after installing or reconfiguring ufw, firewalld, or a custom iptables script.
• sudo iptables -t nat -L DOCKER reports No chain/target/match by that name.

Common Root Causes

• iptables was flushed — iptables -F, a firewalld reload, or a ufw reset wiped Docker’s chains while the daemon still expected them.
• A firewall service started after Docker and reset the ruleset, removing the DOCKER chains.
• Manual iptables editing deleted or renamed a Docker-managed chain.
• iptables disabled for Docker in the past ("iptables": false) then partially re-enabled, leaving inconsistent state.
• nftables/iptables backend mismatch — the host switched backends and the chains Docker created are no longer visible to the active tool.

Diagnostic Workflow

Confirm which Docker chains exist (or do not) in the NAT and filter tables:

sudo iptables -t nat -L DOCKER -n
sudo iptables -L DOCKER -n
sudo iptables -L DOCKER-USER -n

Check the active iptables backend, since a legacy/nft mismatch hides chains:

sudo iptables --version
sudo update-alternatives --display iptables 2>/dev/null

See whether a firewall service is racing Docker:

systemctl status firewalld ufw docker --no-pager | grep -i active

Read the daemon log for the exact rule it failed to insert:

journalctl -u docker --since '15 min ago' | grep -i iptables

Example Root Cause Analysis

An operator hardened a host by adding a custom iptables -F && iptables -P INPUT DROP script that ran on boot after Docker. The next container start failed with iptables: No chain/target/match by that name. Inspecting the NAT table confirmed the damage:

$ sudo iptables -t nat -L DOCKER -n
iptables: No chain/target/match by that name.

The boot script had flushed every table, deleting Docker’s DOCKER chain, so the daemon had nowhere to add the DNAT rule for the published port. Because Docker recreates its chains on startup, the fix was simply to restart the daemon:

sudo systemctl restart docker
sudo iptables -t nat -L DOCKER -n     # chain now present

To prevent recurrence, the hardening script was rewritten to insert rules into DOCKER-USER (Docker’s designated user chain) rather than flushing all tables, and ordered to run before Docker or to reload Docker afterward.

Prevention Best Practices

• Never iptables -F on a Docker host; put custom rules in the DOCKER-USER chain, which Docker preserves and evaluates first.
• Order boot/firewall units so any tool that resets iptables runs before docker.service, or restart Docker after it.
• Prefer firewalld/ufw integration patterns that leave Docker’s chains intact rather than replacing the whole ruleset.
• Keep a single iptables backend (legacy vs nft) consistent across the host.
• After any manual firewall change, verify with sudo iptables -t nat -L DOCKER -n and restart Docker if the chains are gone.

Quick Command Reference

sudo iptables -t nat -L DOCKER -n        # verify NAT chain exists
sudo iptables -L DOCKER-USER -n          # your safe insertion point
systemctl status firewalld ufw           # firewall services that may flush
sudo systemctl restart docker            # recreate Docker's chains
journalctl -u docker | grep -i iptables  # exact failing rule

Conclusion

iptables: No chain/target/match by that name means Docker’s firewall chains were removed after the daemon created them — almost always a flush from a firewall reload or hardening script. Restarting Docker recreates the chains and clears the error; keeping custom rules in DOCKER-USER and never flushing all tables prevents it from returning. See more networking fixes in the Docker guides.