🚨 Docker Error Guide: 'failed to create endpoint on network bridge: address already in use' — Port/IP Clash

Overview

When Docker attaches a container to a network it creates an endpoint — a virtual interface with an IP and any published port mappings. If the host port or the requested static IP is already taken, endpoint creation fails and the container will not start:

Error response from daemon: failed to create endpoint web on network bridge: 
Bind for 0.0.0.0:8080 failed: port is already allocated

A static-IP collision on a user-defined network produces the same class of error:

Error response from daemon: failed to create endpoint api on network myapp_backend: 
Address already in use

Symptoms

• docker start <container> or docker compose up fails at the networking step; the container never reaches running.
• The image ran before but now fails after a crash or an unclean shutdown.
• Removing and recreating the container fixes it — evidence of a stale endpoint.
• Two containers request the same --ip on the same network.

Common Root Causes

• Host port already allocated — another container or host process holds the published port (the classic bind conflict wrapped in endpoint creation).
• Stale endpoint left behind — an unclean daemon restart or SIGKILL left the old endpoint registered so the new one collides.
• Duplicate static IP — two containers pin the same --ip/ipv4_address on one network.
• A leftover docker-proxy process still holds the host port from a crashed container.
• Network recreated while a container held an endpoint, leaving an orphaned reservation.

Diagnostic Workflow

Identify whether the clash is a host port or an IP. For a port, find the listener:

sudo ss -ltnp 'sport = :8080'
docker ps --filter "publish=8080"

Inspect the target network’s existing endpoints and assigned IPs:

docker network inspect myapp_backend

Look at what the failing container requested:

docker inspect --format '{{json .NetworkSettings.Networks}}' <container>
docker inspect --format '{{json .HostConfig.PortBindings}}' <container>

Find and clear a stale docker-proxy still holding the port:

sudo lsof -i :8080 -sTCP:LISTEN | grep docker-proxy

Read the daemon log around the failure:

journalctl -u docker --since '10 min ago' | grep -i 'endpoint\|already'

Example Root Cause Analysis

After a host lost power, a container refused to start with failed to create endpoint web on network bridge: Bind for 0.0.0.0:8080 failed: port is already allocated. docker ps showed nothing on 8080, but sudo lsof -i :8080 revealed a stranded docker-proxy process still bound to the port — a remnant of the container that was running when power was cut. Docker’s userland proxy had not been cleaned up on the hard reboot.

Because no live container owned it, the safe fix was to disconnect the ghost endpoint and recreate the container:

docker network disconnect -f bridge web
docker rm -f web
docker compose up -d web

Recreating the container forced a fresh endpoint and a clean port binding. Where a stranded docker-proxy persists, restarting the daemon (sudo systemctl restart docker) reliably clears orphaned proxies.

Prevention Best Practices

• Always publish unique host ports and bind to a specific interface where possible (127.0.0.1:8080:80).
• Avoid pinning static container IPs unless required; let Docker’s IPAM assign them.
• If you must use static IPs, allocate them from a documented plan so two containers never request the same address.
• Shut down cleanly with docker compose down so endpoints and docker-proxy processes are released.
• After an unclean host restart, sudo systemctl restart docker to clear orphaned endpoints before troubleshooting further.

Quick Command Reference

sudo ss -ltnp 'sport = :8080'              # host port listener
sudo lsof -i :8080 | grep docker-proxy     # stranded proxy
docker network inspect myapp_backend        # endpoints + IPs in use
docker network disconnect -f bridge <ctr>   # clear a stale endpoint
docker rm -f <container>                     # recreate for a fresh endpoint
sudo systemctl restart docker               # clear orphaned proxies

Conclusion

failed to create endpoint on network bridge: address already in use means the endpoint’s host port or static IP is already claimed — often by a live conflict, sometimes by a stale reservation after an unclean shutdown. Determine whether it is a port or IP clash, free the resource or clear the stale endpoint, and recreate the container. Unique ports, IPAM-assigned IPs, and clean teardowns prevent it. See related fixes in the Docker guides.