LocalStack "Connection refused" on port 4566 in CI

By Kaveh Alemi·Latchkey

LocalStack exposes all AWS services on a single edge port, 4566. A connection refused there means the container has not finished starting, or your client is pointed at a host/port where LocalStack is not listening.

What this error means

Tests that use AWS SDK calls against LocalStack fail with "Connection refused" or "ECONNREFUSED 127.0.0.1:4566" early in the job, before the container is healthy.

botocore.exceptions.EndpointConnectionError: Could not connect to the endpoint URL:
"http://localhost:4566/"
ConnectionRefusedError: [Errno 111] Connection refused

Common causes

The container is not ready yet

The test starts issuing AWS calls before LocalStack finishes booting and reports healthy on 4566.

Wrong host from inside another container

A test running in a sibling container uses localhost:4566 instead of the LocalStack service name, so it hits nothing.

How to fix it

Wait for LocalStack to be ready

1. Poll the health endpoint until services report running.
2. Only then run the tests that call AWS.
3. Use a service healthcheck when running as a CI service container.

until curl -sf http://localhost:4566/_localstack/health; do sleep 2; done

Point the endpoint at the right host

From another container, use the LocalStack service name; set a single endpoint URL for the SDK.

env:
  AWS_ENDPOINT_URL: http://localstack:4566

How to prevent it

• Gate AWS calls behind a LocalStack health check.
• Use the service name, not localhost, from sibling containers.
• Set AWS_ENDPOINT_URL once so every client agrees.

Frequently asked questions

Related guides

References

• Terraform documentation
• GitHub Actions documentation