docker: driver failed programming external connectivity (iptables)

Hi, it's BlueByte. If docker run -p suddenly refuses to publish a port and you changed the firewall recently, this one has a very specific cause — and a clean fix. Let's read the error, confirm what happened, rebuild what was lost, and make sure the next firewall reload does not undo it.

What the error is actually telling you

Publishing a port fails like this:

docker: Error response from daemon: driver failed programming external
connectivity on endpoint web: (iptables failed: iptables -t nat -A DOCKER ...
No chain/target/match by that name)

You might also see it as Failed to program NAT chain: ... No chain/target/match by that name, or on docker compose up simply as driver failed programming external connectivity. Read the last line: the daemon tried to add a NAT rule and the DOCKER chain it needs is missing. Nothing is corrupted — your image, compose file, and port number are fine. The problem is the host's firewall state underneath Docker.

Why a firewall reload wipes Docker's chain

When Docker starts a container with a published port, it creates a DOCKER chain and per-container rules in the nat table. Something deleted that chain while the daemon was still running. The usual suspects:

• A firewall reload — firewall-cmd --reload, a ufw enable/reload, or netfilter-persistent — that rebuilt the ruleset from its own config, which does not include Docker's chain.
• A manual iptables-restore without --noflush, which replaces the whole table and takes Docker's chain with it.
• A hardening tool or cron job that flushes iptables on a schedule.

First, confirm the chain is actually gone

You do not have to guess. Check whether the chain exists:

sudo iptables -t nat -L DOCKER -n

No chain/target/match by that name confirms it was wiped. Then find what wiped it — look at the services that rewrite iptables and when they last ran:

systemctl status firewalld ufw netfilter-persistent
sudo journalctl -u firewalld --since "15 min ago"

If the breakage lines up with a reload or a reboot, that is your cause.

Restart the daemon to rebuild the chain

Restarting Docker recreates its chains and per-container rules. Nothing to memorize here — one command does it:

sudo systemctl restart docker
sudo iptables -t nat -L DOCKER -n   # the chain and your rule are back

Then keep the next reload from taking it out. On a firewalld host, run firewalld and Docker's integration together — Docker installs its rules through firewalld, so a reload re-applies them instead of dropping them:

sudo firewall-cmd --reload
sudo iptables -t nat -L DOCKER -n   # still present

If you script changes with iptables-restore, add --noflush so it appends rather than replacing the whole table.

A real case: a reload at 2pm

Say every docker run -p has failed since you tweaked a firewalld rule. iptables -t nat -L DOCKER -n returns "No chain/target/match by that name", and journalctl -u firewalld shows a reload two minutes before the failures started. That is the fingerprint — the reload flushed the chain. sudo systemctl restart docker rebuilds it, the same iptables command now lists the chain, and your container publishes. The next firewalld reload leaves it alone, because Docker registered through firewalld rather than around it.

Check a published port end to end

Confirm it really works, not just that the chain looks right:

docker run --rm -p 8080:80 nginx:alpine
curl -sSI http://localhost:8080 | head -1   # HTTP/1.1 200 OK

A 200 plus a visible rule in iptables -t nat -L DOCKER -n means the fix held.

Keep it from coming back

On boot, order the units so the firewall starts before Docker, or let firewalld own the integration so reloads never strip the chain. On a host you reload often, avoid a bare iptables -F or an unscoped iptables-restore against the nat table — scope any flush to your own chains so Docker's survive.

How this differs from "port is already allocated"

Bind for 0.0.0.0:8080 failed: port is already allocated is the opposite case — the chain is fine, but another container already holds the port. And setting "iptables": false in /etc/docker/daemon.json silences this error only by disabling published-port connectivity entirely, so outside traffic can no longer reach your containers. Leave iptables management on unless you manage every NAT rule by hand. Next time a port publish fails right after a firewall change, check the DOCKER chain first — it is almost always this.