LocalStack port 4566 already in use / bind conflict in CI

By Daniel Zoghalchali·Latchkey

LocalStack binds its edge port 4566 on start. If another service, a leftover LocalStack container, or a service-container mapping already holds 4566, the bind fails and LocalStack never comes up.

What this error means

Starting LocalStack fails with "Bind for 0.0.0.0:4566 failed: port is already allocated" or "address already in use", so the health endpoint never responds.

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

Common causes

A leftover LocalStack container holds the port

A previous run did not clean up, so an old container still binds 4566 when the new one tries to start.

Another service mapped the same port

A different service container or process already published 4566, causing a bind conflict.

How to fix it

Remove leftovers and confirm the port is free

1. Stop and remove any existing LocalStack container.
2. Confirm nothing else listens on 4566.
3. Start LocalStack again once the port is free.

docker rm -f localstack 2>/dev/null || true
ss -ltn | grep 4566 || echo "4566 free"

Map LocalStack to a different host port

If 4566 is genuinely needed by something else, publish LocalStack on another host port and point the endpoint URL at it.

docker run -p 4577:4566 localstack/localstack:3
# then endpoint_url=http://localhost:4577

How to prevent it

• Clean up LocalStack containers at the end of each job.
• Check that 4566 is free before starting LocalStack.
• Use a distinct host port if 4566 is reserved by another service.

Frequently asked questions

Related guides

References

• GitHub Actions documentation