LocalStack botocore "Could not connect to the endpoint URL http://localhost:4566" in CI

By Kaveh Alemi·Latchkey

Your AWS SDK call targeted the LocalStack endpoint at http://localhost:4566 but the connection was refused. LocalStack is either not up yet, not on localhost from the client, or on a different port.

What this error means

A boto3/botocore call fails with "Could not connect to the endpoint URL: http://localhost:4566/...". The client is pointed at LocalStack, but nothing is listening where it looks.

botocore.exceptions.EndpointConnectionError:
Could not connect to the endpoint URL: "http://localhost:4566/"

Common causes

LocalStack is not ready or not running

The client ran before LocalStack finished booting, or the container is not up, so 4566 refuses the connection.

The client host differs from where LocalStack listens

From inside another container localhost is not the LocalStack container; you may need a service host name instead.

How to fix it

Wait for readiness, then point at the right host

1. Poll the health endpoint until LocalStack is ready.
2. From the runner host use http://localhost:4566; from another container use the service host name.
3. Set the endpoint URL consistently for every client.

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

Configure the endpoint URL explicitly

Set the AWS endpoint URL so the SDK targets LocalStack rather than real AWS.

import boto3
s3 = boto3.client("s3", endpoint_url="http://localhost:4566")

How to prevent it

• Wait on the health endpoint before making SDK calls.
• Use the correct host name for where the client actually runs.
• Set the endpoint URL centrally so every client agrees.

Frequently asked questions

Related guides

References

• GitHub Actions documentation