Docker Compose Network: “Port is Already Allocated” Fix

by

Root Cause Diagnosis

This error occurs when Docker attempts to bind a host port defined in your docker-compose.yml file to a container port, but that host port is already in use by another running service, a orphaned Docker container, or an active network socket. In bridge network configurations—whether default, custom, or marked as external: true—port mappings strictly require exclusive binding rights to the host’s network interfaces.

Quick Fix

Identify the process or container locking the port and stop it immediately. Replace 8080 with your conflicting port number:

Bash

# Find and terminate the process holding port 8080 (Linux/macOS)
sudo lsof -i :8080 -t | xargs -r sudo kill -9

# Or stop all conflicting Docker containers
docker ps -q --filter "publish=8080" | xargs -r docker stop

Step-by-Step Resolution

Step 1: Identify the Conflicting Process

Find out which application or container is occupying the host port.

  • On Linux/macOS:
    Bashsudo netstat -tulpn | grep :8080 # OR sudo ss -tulpn | grep :8080
  • On Windows (PowerShell):
    PowerShellGet-Process -Id (Get-NetTCPConnection -LocalPort 8080).OwningProcess

Step 2: Remove Orphaned Docker Containers/Networks

Often, a previously failed docker compose up or crashed container leaves the port bound in the Docker bridge network registry.

Bash

# Stop and remove orphaned containers for the project
docker compose down --remove-orphans

# Clean up dangling bridge networks and unused resources
docker network prune -f

Step 3: Resolve Port Conflict in Configuration

If the host port is required by a persistent system service (such as system Nginx, Apache, or MySQL), modify the host port binding in docker-compose.yml to map to an available host port:

YAML

version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      # Format: "HOST_PORT:CONTAINER_PORT"
      - "8081:80" # Changed host port from 8080 to 8081
    networks:
      - custom_external_net

networks:
  custom_external_net:
    external: true

Step 4: Verify External Network and Restart

Ensure the external bridge network exists and redeploy:

See also  Fix: Docker exited with code 137 on low-memory ARM instances

Bash

# Verify external network existence
docker network ls | grep custom_external_net

# Bring up the stack
docker compose up -d

Why This Fails for Some Users

  • Host Network Mode Conflicts: If another service uses network_mode: "host", it bypasses Docker’s virtual bridge interface and binds directly to the host IP, bypassing standard Docker container port checks until launch.
  • WSL2 / Windows Port Exclusion Range: On Windows using WSL2, Hyper-V or Windows NAT (iphlpsvc) frequently reserves dynamic port ranges upon reboot, locking ports even when no process shows up in netstat.
    • Fix: Check reserved ranges using netsh interface ipv4 show excludedportrange protocol=tcp and restart the hns / winnat service.
  • Docker Desktop Virtualization Layer (macOS/Windows): The Docker daemon proxy (com.docker.backend or vpnkit) can crash and hold onto host ports without updating the state of the internal bridge network. Restructure requires restarting Docker Desktop completely.
  • Systemd Services Auto-Starting on Boot: Services like systemd-resolved (port 53), local postgresql (port 5432), or nginx (port 80) automatically launch at boot time before Docker containers start, creating intermittent startup order issues across server reboots.

Leave a Comment