LocalStack S3 path-style addressing / bucket host resolution in CI

By Kaveh Alemi·Latchkey

By default S3 SDKs use virtual-host addressing, resolving bucket-name.localhost (or bucket-name.s3.amazonaws.com). Against LocalStack that host does not resolve, so S3 calls fail. Enabling path-style addressing routes requests to localhost:4566/bucket-name instead.

What this error means

S3 operations against LocalStack fail with a DNS or connection error for bucket.localhost (or the bucket subdomain), while non-S3 services work fine.

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

Common causes

Virtual-host addressing resolves a nonexistent host

The SDK prepends the bucket as a subdomain, producing bucket.localhost, which has no DNS record on the runner.

Path-style addressing was not enabled

Without forcing path style, the client keeps using virtual-host URLs that LocalStack cannot serve.

How to fix it

Force path-style addressing

Configure the S3 client to use path-style so requests go to localhost:4566/bucket instead of bucket.localhost.

import boto3
from botocore.config import Config
s3 = boto3.client("s3", endpoint_url="http://localhost:4566",
                  config=Config(s3={"addressing_style": "path"}))

Set the equivalent flag in other SDKs

For the AWS CLI and other SDKs, enable the path-style / force-path-style option so S3 URLs resolve against LocalStack.

aws --endpoint-url=http://localhost:4566 s3api list-objects --bucket mybucket

How to prevent it

• Enable path-style S3 addressing for LocalStack clients.
• Avoid relying on virtual-host bucket DNS on the runner.
• Keep S3 client config consistent across the test suite.

Frequently asked questions

Related guides

References

• GitHub Actions documentation