How to fix Cannot start service web: driver failed programming external connectivity on endpoint in Docker

DockerINTERMEDIATEHIGHUpdated Dec 6, 2025· 235 views

Docker cannot configure network port forwarding. Usually caused by port conflicts, firewall rules, or Docker network driver issues. Restart Docker or check for port conflicts.

Quick fix

Fixes Cannot start service web: driver failed programming external connectivity on endpoint

# Check what is using the port
sudo lsof -i :PORT_NUMBER
sudo netstat -tlnp | grep PORT_NUMBER

# Check Docker containers using ports
docker ps --format "table {{.Names}}	{{.Ports}}"
  1. Check for port conflicts
  2. Restart Docker daemon
  3. Remove stale containers and networks
  4. Check and reset iptables
docker — error
# Check what is using the port
sudo lsof -i :PORT_NUMBER
sudo netstat -tlnp | grep PORT_NUMBER
# Check Docker containers using ports
docker ps --format "table {{.Names}}	{{.Ports}}"
Cannot start service web: driver failed programming external connectivity on endpoint

What this error means

This error occurs when Docker network driver fails to set up port forwarding rules for a container. Docker uses iptables (on Linux) to manage network connectivity between containers and the host network. When this configuration fails, containers cannot expose ports externally. The error often appears with Docker Compose when starting services with port mappings. It indicates a problem at the network infrastructure level rather than the application level.

Typical symptoms

  • docker-compose up fails for a service with port mappings
  • Container starts but port forwarding is not configured
  • Error mentions specific endpoint or network driver
  • Services without port mappings start successfully
  • Problem persists across container restarts

Common causes

  1. Port is already bound by another process or container
  2. Previous container did not cleanly release the port
  3. Docker network or iptables rules are corrupted
  4. Firewall software conflicts with Docker (ufw, firewalld)
  5. Docker daemon encountered an internal error
  6. Network interface referenced by Docker no longer exists
  7. IPv6 networking issues

How to fix "Cannot start service web: driver failed programming external connectivity on endpoint"

1Check for port conflicts

See if another process is using the port:

bash
# Check what is using the port
sudo lsof -i :PORT_NUMBER
sudo netstat -tlnp | grep PORT_NUMBER

# Check Docker containers using ports
docker ps --format "table {{.Names}}	{{.Ports}}"

Stop any conflicting process or container.

2Restart Docker daemon

Often the simplest fix is restarting Docker:

bash
sudo systemctl restart docker

# Or on older systems
sudo service docker restart

This resets network state and clears stale iptables rules.

3Remove stale containers and networks

Clean up orphaned resources:

bash
# Stop and remove all containers
docker stop $(docker ps -aq)
docker rm $(docker ps -aq)

# Remove unused networks
docker network prune

# For Docker Compose specifically
docker-compose down --remove-orphans
4Check and reset iptables

Docker manages iptables rules. Reset if corrupted:

bash
# View Docker iptables rules
sudo iptables -L -n | grep -i docker

# Restart Docker to rebuild rules
sudo systemctl restart docker

# If issues persist, flush and restart
sudo iptables -t nat -F DOCKER
sudo systemctl restart docker

Warning: Flushing iptables affects all Docker networking.

5Check firewall compatibility

Some firewalls conflict with Docker:

bash
# UFW (Ubuntu)
sudo ufw status
# May need to allow Docker traffic

# firewalld (CentOS/RHEL)
sudo firewall-cmd --list-all

# Check if firewall is blocking Docker
sudo journalctl -u docker | grep -i firewall

Consider configuring firewall to trust docker0 interface.

6Recreate Docker networks

If specific networks are problematic:

bash
# List networks
docker network ls

# Remove and recreate the problematic network
docker network rm <network_name>

# For Compose, recreate networks
docker-compose down
docker-compose up -d

Compose will recreate networks automatically.

Advanced notes

Docker Desktop: On macOS/Windows, restart Docker Desktop from the system tray. The networking stack is different from Linux.

IPv6 Issues: If you see IPv6-related errors, disable IPv6 in Docker or configure it properly:

json
{
  "ipv6": false
}

Add to /etc/docker/daemon.json.

VPN Conflicts: VPN software often modifies routing tables and can conflict with Docker networking. Try disconnecting VPN or configuring Docker to use a different subnet in daemon.json.

Frequently asked questions

What does "Cannot start service web: driver failed programming external connectiv" mean?
This error occurs when Docker network driver fails to set up port forwarding rules for a container. Docker uses iptables (on Linux) to manage network connectivity between containers and the host network. When this configuration fails, containers cannot expose ports externally.
How do I fix "Cannot start service web: driver failed programming external connectiv"?
Docker cannot configure network port forwarding. Usually caused by port conflicts, firewall rules, or Docker network driver issues. Restart Docker or check for port conflicts.
What causes "Cannot start service web: driver failed programming external connectiv"?
Port is already bound by another process or container Previous container did not cleanly release the port Docker network or iptables rules are corrupted
Is the "Cannot start service web: driver failed programming external connectiv" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading