Docker `port is already allocated` Means Something Else Got There First and You Should Find It Before You Randomly Rewrite Compose Files

Why this error matters: when Docker says a port is already allocated, the problem is usually not “Docker is broken.” The problem is that two things want the same host port and only one of them can win.

A classic local-dev failure looks like this:

Error response from daemon: driver failed programming external connectivity on endpoint ...
Bind for 0.0.0.0:5432 failed: port is already allocated

People often react by changing random lines in Compose until the error disappears. That works just often enough to create worse confusion later.

What the error actually means

The published host port is already in use by either:

1. another Docker container
2. a non-Docker process on your machine
3. an old compose stack you forgot was still running

Docker is not complaining about the internal container port. It is complaining about the host side of the mapping.

First, identify who owns the port

If you suspect another container:

docker ps --format "table {{.Names}}\t{{.Ports}}"

If you suspect a local process outside Docker:

lsof -iTCP:5432 -sTCP:LISTEN -n -P

or:

ss -ltnp | grep 5432

That tells you whether the conflict is Postgres.app, another container, a local dev server, or something more forgettable like an old tunnel.

Then choose the right fix

If another container owns the port

Stop it if it is not needed:

docker stop old-postgres
docker rm old-postgres

If it belongs to another compose project:

docker compose down

inside that project directory.

If a host process owns the port

Either stop that process:

brew services stop postgresql@16

or remap the container to a different host port:

ports:
  - "5433:5432"

That means:

1. host listens on 5433
2. container still listens on 5432

Verify after changing it

After a fix, confirm what is now listening:

docker ps --format "table {{.Names}}\t{{.Ports}}"
lsof -iTCP:5433 -sTCP:LISTEN -n -P

If you changed Compose, recreate the service:

docker compose up -d --force-recreate

The most common bad habit

People change:

- "5432:5432"

to:

- "15432:15432"

without realizing they also changed the container port incorrectly. Usually you want:

- "15432:5432"

because the application inside the container still expects its original internal port.

Final recommendation

When Docker says a port is already allocated, do not start guessing. Identify the existing listener first, decide whether to stop it or remap around it, and verify the result with a real port check. Most fixes take two commands once you know who owns the port.

Sources

• Docker port publishing documentation
• Docker Compose file reference