This error occurs when Docker expects firewalld to manage network rules but the firewall service is not running. The fix involves either starting firewalld or configuring Docker to work without it by restarting the Docker daemon.
Docker on Linux uses iptables to manage network traffic for containers. When Docker is configured to integrate with firewalld (the dynamic firewall daemon used by RHEL, CentOS, Fedora, and other systemd-based distributions), it expects firewalld to be running so it can properly set up NAT rules and port forwarding for containers. The error "driver failed programming external connectivity: firewalld is not running" indicates that Docker's network driver attempted to configure port publishing rules through firewalld, but the firewalld service was stopped or disabled. This typically happens when: - The system was rebooted and firewalld didn't start automatically - An administrator manually stopped firewalld - Docker was installed after firewalld was disabled - A system update changed firewall configuration Without proper firewall rules, Docker cannot publish container ports to the host, preventing external access to your containerized applications.
First, verify whether firewalld is installed and check its current status:
# Check if firewalld is installed
rpm -qa | grep firewalld
# or on Debian-based systems
dpkg -l | grep firewalld
# Check firewalld service status
sudo systemctl status firewalldIf the output shows "inactive (dead)" or "disabled", the service is not running. If firewalld is not installed at all, you'll need to either install it or configure Docker to use iptables directly.
If firewalld is installed but stopped, start it:
# Start firewalld
sudo systemctl start firewalld
# Verify it's running
sudo systemctl status firewalldYou should see "active (running)" in the output. If the service fails to start, check the logs with journalctl -u firewalld for error details.
After starting firewalld, restart Docker so it can properly configure its network rules:
# Restart Docker
sudo systemctl restart docker
# Verify Docker is running
sudo systemctl status dockerDocker will now detect firewalld and configure its iptables rules through the firewalld interface.
Verify the fix by running a container with port mapping:
# Test with a simple nginx container
docker run -d --name test-nginx -p 8080:80 nginx
# Verify it's running
docker ps
# Test connectivity
curl http://localhost:8080If the container starts successfully and you can access it, the issue is resolved.
To prevent this error from recurring after reboots, enable firewalld to start automatically:
# Enable firewalld on boot
sudo systemctl enable firewalld
# Verify it's enabled
sudo systemctl is-enabled firewalldThe output should show "enabled".
If you prefer not to use firewalld, you can configure Docker to manage iptables directly. First, stop and disable firewalld:
# Stop and disable firewalld
sudo systemctl stop firewalld
sudo systemctl disable firewalldThen ensure iptables is available and restart Docker:
# Install iptables if needed (RHEL/CentOS)
sudo yum install iptables-services
# Start iptables
sudo systemctl start iptables
sudo systemctl enable iptables
# Clear any stale rules and restart Docker
sudo iptables -t filter -F
sudo iptables -t filter -X
sudo systemctl restart dockerNote: This approach requires you to manually manage firewall rules for host security.
If the error occurs intermittently after reboots, Docker may be starting before firewalld. Create a systemd override to ensure correct ordering:
# Create override directory
sudo mkdir -p /etc/systemd/system/docker.service.d/
# Create override file
sudo tee /etc/systemd/system/docker.service.d/firewalld.conf << 'EOF'
[Unit]
After=firewalld.service
Requires=firewalld.service
EOF
# Reload systemd and restart Docker
sudo systemctl daemon-reload
sudo systemctl restart dockerThis ensures Docker waits for firewalld to be fully started before initializing.
For better integration, add the docker0 interface to firewalld's trusted zone:
# Add docker0 to trusted zone
sudo firewall-cmd --permanent --zone=trusted --add-interface=docker0
# Enable masquerading for container internet access
sudo firewall-cmd --permanent --zone=public --add-masquerade
# Reload firewalld
sudo firewall-cmd --reload
# Restart Docker
sudo systemctl restart dockerThis configuration allows containers to communicate freely while maintaining firewall protection on other interfaces.
Understanding Docker and firewalld interaction:
Docker can work with different firewall backends. On systems with firewalld, Docker detects it and uses firewalld's D-Bus interface to manage rules. If firewalld is stopped, Docker falls back to direct iptables manipulation, but only if it's restarted after the firewall change.
The --iptables flag:
If you consistently run without firewalld, you can disable Docker's automatic iptables management by setting --iptables=false in /etc/docker/daemon.json:
{
"iptables": false
}However, this means you must manually configure all port forwarding rules, which is not recommended for most users.
nftables vs iptables:
Modern Linux distributions are transitioning from iptables to nftables. Docker's firewalld integration generally handles this transparently, but mismatches between Docker's expected backend and the system's actual backend can cause issues. Check your system with:
firewall-cmd --state
nft list rulesetSELinux considerations:
On SELinux-enabled systems, firewall rule changes may be blocked by SELinux policies. If firewalld starts but Docker still fails, check for SELinux denials:
sudo ausearch -m avc -ts recentContainer networking modes:
This error only affects containers using bridge networking with port publishing. Containers using --network=host or --network=none bypass Docker's NAT rules entirely and won't trigger this error.
image operating system "linux" cannot be used on this platform
How to fix 'image operating system linux cannot be used on this platform' in Docker
manifest unknown: manifest unknown
How to fix 'manifest unknown' in Docker
cannot open '/etc/passwd': Permission denied
How to fix 'cannot open: Permission denied' in Docker
Error response from daemon: failed to create the ipvlan port
How to fix 'failed to create the ipvlan port' in Docker
toomanyrequests: Rate exceeded for anonymous users
How to fix 'Rate exceeded for anonymous users' in Docker Hub