ProjectStack
docker

ERROR: for X: Cannot start service X: driver failed programming external connectivity on endpoint X

Docker Compose couldn't start the service because it couldn't bind the published port. This is the Compose equivalent of the 'address already in use' error — a port conflict is preventing Docker from setting up the network routing for the container.

Common causes

  • Another container or service is already using the port defined in the Compose file
  • A previous docker-compose up left containers running that weren't cleaned up
  • A local development server or system service is bound to the same port
  • Two services in the same Compose file are both mapped to the same host port

How to fix it

  1. Stop all running Compose services first: docker-compose down
  2. Find what's using the port: lsof -i :PORT or netstat -tulpn | grep PORT
  3. Change the host port in docker-compose.yml: ports: - "8081:80" instead of "8080:80"
  4. Stop the conflicting local service, then re-run docker-compose up

Example

$ docker-compose up ERROR: for nginx: Cannot start service nginx: driver failed programming external connectivity on endpoint: Error starting userland proxy: listen tcp4 0.0.0.0:80: bind: address already in use

Port 80 is already in use by a local web server, preventing Docker Compose from binding to it

Related Docker Errors

Cannot connect to Docker daemonPermission denied connecting to Docker socketDocker daemon not running on this hostImage not found or pull access deniedImage manifest not found (tag doesn't exist)

Browse more errors

The Developer Hub covers 150+ errors across Git, npm, Node.js, Python, TypeScript, and Docker — with plain-English explanations and fix steps.