LocalStack S3 and other services refuse connections on 127.0.0.1:4566
Connection refused 127.0.0.1:4566Short answer
Connection refused on 4566 means nothing answered at the address you used. Check where the client runs. From the host, port 4566 must be published. From another container, use the LocalStack service name on a shared network, not localhost. From another machine, LocalStack must listen on all interfaces. LocalStack only binds IPv4.
Fix it fast
1Find out which cause you have
Check that the LocalStack container is running and that port 4566 is published, then call it from the host with an explicit endpoint.
docker ps --format '{{.Names}} {{.Ports}}' | grep -i localstack aws --endpoint-url http://localhost:4566 s3api list-buckets2Match what you see, then jump to its fix
- 1
docker ps shows the container with no 4566 mapping, and the client runs on your machinePort 4566 is not published to the hostFix - 2
The call works from your terminal but fails inside your own app containerThe client runs in another container and uses localhostFix - 3
Refused from the host even though 4566 is published; the endpoint uses a name such as localhost that your tools resolve to ::1The name resolves to IPv6 and LocalStack only listens on IPv4Fix - 4
Works on the Docker host, refused from another computer or a VMThe client is on a different machineFix
- 1
What does the error look like?
Connection refused 127.0.0.1:4566
Cause 1 of 4
Port 4566 is not published to the host
1Check
With plain docker or docker compose, you must map the port yourself. If you want another host port, LocalStack has the GATEWAY_LISTEN variable.
docker port localstack-main2Fix
Publish 4566 and call LocalStack through the endpoint URL.
services:
localstack:
image: localstack/localstack
ports:
- "4566:4566"3Verify
The CLI call returns a response instead of a connection error.
aws --endpoint-url http://localhost:4566 s3api list-bucketsConfirmed by docs.localstack.cloud
Cause 2 of 4
The client runs in another container and uses localhost
1Check
Inside your app container, localhost is the app container itself, not LocalStack. Containers reach each other by service name on a shared network.
docker network inspect ls --format '{{range .Containers}}{{.Name}} {{end}}'2Fix
Put both services on one user-defined network, set MAIN_DOCKER_NETWORK on LocalStack, and use the LocalStack hostname as the endpoint.
services:
localstack:
image: localstack/localstack
environment:
MAIN_DOCKER_NETWORK: ls
networks:
- ls
your_container:
build: .
networks:
- ls
networks:
ls:
name: ls
# endpoint in the app: http://localstack:45663Verify
From the app container, list buckets against the service name.
docker compose exec your_container aws --endpoint-url http://localstack:4566 s3api list-bucketsConfirmed by docs.localstack.cloud
Cause 3 of 4
The name resolves to IPv6 and LocalStack only listens on IPv4
1Check
LocalStack only binds to IPv4 addresses such as 127.0.0.1. A client that tries an IPv6 address first gets a refusal.
getent hosts localhost2Fix
Use the IPv4 address in the endpoint URL.
aws --endpoint-url http://127.0.0.1:4566 s3api list-buckets3Verify
The same call through 127.0.0.1 returns buckets, and your SDK endpoint_url is set to that address.
aws --endpoint-url http://127.0.0.1:4566 s3api list-bucketsConfirmed by docs.localstack.cloud
Cause 4 of 4
The client is on a different machine
1Check
By default LocalStack listens on the host loopback. A separate host needs LocalStack to listen on all interfaces.
docker port localstack-main2Fix
Set GATEWAY_LISTEN to 0.0.0.0 on LocalStack, publish 4566, and use the Docker host's address in the endpoint.
environment:
GATEWAY_LISTEN: 0.0.0.0
ports:
- "4566:4566"
# client: http://<host-address>:45663Verify
Call the endpoint from the other machine.
aws --endpoint-url http://<host-address>:4566 s3api list-bucketsConfirmed by docs.localstack.cloud
How do I stop it coming back?
- Keep the endpoint URL in one environment variable per environment: localhost:4566 on the host, localstack:4566 in Compose.
- Start the app after LocalStack reports ready, for example with a Compose health check.
- Do not mix names: do not use localhost.localstack.cloud from a container unless you set the container's DNS to LocalStack.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- RaheebA consumer app shipped to both stores from one Flutter codebase on a .NET and Azure back end.
Related fixes
Back end
Node.js S3 client cannot resolve my-bucket.localhost on LocalStack
Error: getaddrinfo ENOTFOUND bucketname.localhost
The SDK puts the bucket name in the hostname (virtual-hosted style), so it looks up my-bucket.localhost, which does not resolve.
3 causes, each with a fixServers
docker login to Amazon ECR fails with: Cannot perform an interactive login from a non TTY device
Cannot perform an interactive login from a non TTY device
Docker asked for a password because none reached it, and a pipe or script has no keyboard to answer.
3 causes, each with a fixServers
sam local fails: Running AWS SAM projects locally requires Docker
Cannot connect to the Docker daemon. Is the docker daemon running on this host?
sam local start-api and sam local invoke run your function inside a Docker container, so SAM stops if it cannot talk to Docker.
3 causes, each with a fixServers
The Java SDK finds no AWS credentials on an EC2 instance or in a container on it
InstanceProfileCredentialsProvider()
The SDK walks a fixed list of credential sources and the EC2 instance role is the last one.
3 causes, each with a fixServers
cdk deploy fails in a GitLab job with spawnSync docker ENOENT
code: 'ENOENT'
ENOENT means the operating system found no docker program to run.
3 causes, each with a fixServers
docker push to Amazon ECR stops with: no basic auth credentials
no basic auth credentials
Docker has no stored login for the registry host in your image tag.
2 causes, each with a fix