Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

LocalStack S3 and other services refuse connections on 127.0.0.1:4566

ErrorConnection refused 127.0.0.1:4566

Short 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.

  • Applies to LocalStack for AWS, Docker Engine 28, Docker Compose 2, AWS CLI 2
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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-buckets
  2. 2Match what you see, then jump to its fix

    1. 1docker ps shows the container with no 4566 mapping, and the client runs on your machinePort 4566 is not published to the hostFix
    2. 2The call works from your terminal but fails inside your own app containerThe client runs in another container and uses localhostFix
    3. 3Refused 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. 4Works on the Docker host, refused from another computer or a VMThe client is on a different machineFix

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-main

2Fix

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-buckets

Confirmed by docs.localstack.cloud

Did this fix it?

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:4566

3Verify

From the app container, list buckets against the service name.

docker compose exec your_container aws --endpoint-url http://localstack:4566 s3api list-buckets

Confirmed by docs.localstack.cloud

Did this fix it?

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 localhost

2Fix

Use the IPv4 address in the endpoint URL.

aws --endpoint-url http://127.0.0.1:4566 s3api list-buckets

3Verify

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-buckets

Confirmed by docs.localstack.cloud

Did this fix it?

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-main

2Fix

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>:4566

3Verify

Call the endpoint from the other machine.

aws --endpoint-url http://<host-address>:4566 s3api list-buckets

Confirmed by docs.localstack.cloud

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.