Docker iptables and nftables Compatibility Troubleshooting

When installing Docker applications via 1Panel on a Debian 12 server, I encountered a very typical problem: containers could be created successfully, but port mapping failed at startup. On the surface it looks like a Docker error, but the actual cause is iptables backend and Docker chain incompatibility.

Symptoms

After Docker container creation completes, the startup phase throws an error:

Error response from daemon: failed to set up container networking:
driver failed programming external connectivity on endpoint ...
Unable to enable OPEN PORT rule:
iptables: No chain/target/match by that name. (exit status 1)

This error can be misleading. The container itself isn't failing to create — the port mapping setup is failing during the Starting phase.

Root Cause

Debian 12 bookworm defaults to iptables-nft, which is the nftables backend. Docker maintains its own DOCKER chain in iptables for bridge networking and port mapping.

When the DOCKER chain in the filter table is incompatible with the nft backend state, you get errors like:

iptables v1.8.9 (nf_tables): chain `DOCKER' in table `filter' is incompatible, use 'nft' tool.

A key detail: the DOCKER chain in the NAT table may still be working normally, so existing port mappings won't necessarily break immediately. What's actually affected is new containers or newly added port mappings.

Quick Diagnosis

First check which backend iptables is currently using:

update-alternatives --query iptables | grep -E 'Status|Value'

Then check the Docker chain in the filter table:

iptables -L DOCKER -n

If you see incompatible or the chain doesn't exist, check the NAT table status:

iptables -t nat -L DOCKER -n

Finally confirm current containers and port mappings:

docker ps --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'

If existing containers are still running normally but new ones won't start, you can pretty much pin it on Docker port mapping and iptables backend compatibility.

Fix Steps

1. Back Up Existing Rules

Always back up before modifying network rules, so you have something to roll back to:

mkdir -p /root/backup-iptables-$(date +%Y%m%d)
iptables-save > /root/backup-iptables-$(date +%Y%m%d)/iptables-all.txt
iptables-save -t nat > /root/backup-iptables-$(date +%Y%m%d)/iptables-nat.txt
docker ps --format '{{.Names}} {{.Image}} {{.Status}}' > /root/backup-iptables-$(date +%Y%m%d)/containers.txt

2. Switch to Legacy Mode

Switch both IPv4 and IPv6 iptables to legacy:

update-alternatives --set iptables /usr/sbin/iptables-legacy
update-alternatives --set ip6tables /usr/sbin/ip6tables-legacy

3. Restart Docker

systemctl restart docker

If containers have restart: always or unless-stopped configured, Docker will automatically bring them back up.

4. Verify

Check if the DOCKER chain displays correctly:

iptables -L DOCKER -n

Confirm container status:

docker ps

Check if critical ports are listening:

ss -tlnp | grep -E ':80 |:443 |:3000 '

If it was an application that failed to install in 1Panel, try reinstalling or restarting the application at this point — it should usually recover.

Notes

• Containers using host network mode are usually unaffected by this issue, e.g., openresty listening directly on host ports.
• Containers using bridge network mode rely on iptables for port mapping — MySQL, new-api, and similar containers will be affected.
• Before fixing, confirm that important containers have a restart policy to avoid Docker restart leaving services without automatic recovery.
• If the system has firewalld enabled, you may also need to check if it has rewritten the rules.
• Don't directly flush iptables rules in production — always back up first.

Environment Record

The environment where this issue occurred was approximately:

Item	Value
System	Debian 12 bookworm
Docker	28.3.2
Panel	1Panel
iptables	v1.8.9
Fix Direction	Switch iptables-nft to iptables-legacy

Summary

The core of this issue isn't the container image or 1Panel itself, but the incompatibility between Docker's iptables chain dependency and Debian's default nftables backend.

When troubleshooting, follow this sequence:

1. Check if the container shows Created successfully but Starting failed
2. Check iptables -L DOCKER -n
3. Confirm iptables current backend
4. Back up rules
5. Switch to legacy
6. Restart Docker and verify container ports

Once you've accurately identified this type of issue, the fix isn't complicated. What you really need to watch out for is the backup and recovery sequence, to avoid affecting already-running containers during troubleshooting.