Node.js S3 client cannot resolve my-bucket.localhost on LocalStack
getaddrinfo ENOTFOUND my-bucket.localhostShort answer
The SDK puts the bucket name in the hostname (virtual-hosted style), so it looks up my-bucket.localhost, which does not resolve. Set forcePathStyle: true in the S3 client, or point the endpoint at s3.localhost.localstack.cloud:4566 so the bucket subdomain resolves to LocalStack.
Fix it fast
1Find out which cause you have
Print the hostname the SDK tried. If the bucket name sits in front of the endpoint host, the client is using virtual-hosted style.
node -e "require('dns').lookup('my-bucket.localhost', console.log)"2Match what you see, then jump to its fix
- 1
The failing host is <bucket>.localhost and your endpoint is http://localhost:4566The S3 client uses virtual-hosted addressing against a bare localhost endpointFix - 2
You want virtual-hosted style, but the endpoint is localhost.localstack.cloud without the s3 prefixThe endpoint host is not the S3 host LocalStack understandsFix - 3
The error appears from inside Docker Compose, or the bucket name contains periodsThe app runs in another container, or the bucket name has dotsFix
- 1
What does the error look like?
getaddrinfo ENOTFOUND my-bucket.localhostError: getaddrinfo ENOTFOUND bucketname.localhost
Cause 1 of 3
The S3 client uses virtual-hosted addressing against a bare localhost endpoint
1Check
The LocalStack S3 docs describe two addressing styles. Virtual-hosted puts the bucket in the host name, path style puts it in the URL path. A host such as my-bucket.localhost has no DNS record on most machines.
grep -rn "endpoint\|forcePathStyle" src/2Fix
Turn on path style in the client. The LocalStack docs name forcePathStyle: true for the JavaScript SDK v3.
import { S3Client } from '@aws-sdk/client-s3';
const s3 = new S3Client({
endpoint: 'http://localhost:4566',
region: 'us-east-1',
forcePathStyle: true,
});3Verify
Run a list call. It now reaches http://localhost:4566/<bucket>.
aws --endpoint-url http://localhost:4566 s3 lsConfirmed by docs.localstack.cloud
Cause 2 of 3
The endpoint host is not the S3 host LocalStack understands
1Check
LocalStack says virtual-hosted style is its default and that the endpoint needs the s3. prefix, so the bucket name can be read from the Host header. Without it, requests go to <bucket>.localhost.localstack.cloud, which LocalStack cannot use to find the bucket.
env | grep AWS_ENDPOINT_URL2Fix
Set the S3-specific endpoint variable next to the general one. The S3 variable wins for S3 calls.
export AWS_ENDPOINT_URL=http://localhost.localstack.cloud:4566
export AWS_ENDPOINT_URL_S3=http://s3.localhost.localstack.cloud:45663Verify
Create and list a bucket with the same environment.
aws s3 mb s3://my-bucket
aws s3 lsConfirmed by docs.localstack.cloud
Cause 3 of 3
The app runs in another container, or the bucket name has dots
1Check
The LocalStack docs list both cases as reasons to use path style: connecting from another container through http://localstack:4566, and bucket names with periods, because the TLS certificate does not cover the extra dot.
grep -n "localstack" docker-compose.yml2Fix
Use the service name as the endpoint host and keep forcePathStyle on.
const s3 = new S3Client({
endpoint: 'http://localstack:4566',
region: 'us-east-1',
forcePathStyle: true,
});3Verify
Run the same call from inside the app container.
docker compose exec app node -e "console.log(process.version)"Confirmed by docs.localstack.cloud
How do I stop it coming back?
- Keep the S3 client creation in one module, so the endpoint and forcePathStyle are set once.
- Read the endpoint from an environment variable, so tests and production use different values.
- Avoid dots in bucket names that tests create.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- Dispatch ProA real-time logistics platform: Flutter apps, Spring Boot services and a Kafka event pipeline on AWS.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
The AWS SDK in Node.js cannot find any credentials
Missing credentials in config, if using AWS_CONFIG_FILE, set AWS_SDK_LOAD_CONFIG=1
The AWS SDK walks a fixed credential chain: code, environment variables, the shared files in ~/.aws, then role sources such as ECS or EC2.
3 causes, each with a fixBack end
AWS SDK for JavaScript v3 cannot find credentials, even for DynamoDB Local
A DynamoDB client pointed at http://localhost:8000 fails with the same message
The SDK walked its default credential provider chain and found nothing.
3 causes, each with a fixBack end
AWS SDK says the security token included in the request is invalid
The security token included in the request is invalid
The call reached AWS but the credentials it carried were refused.
3 causes, each with a fixBack end
Amazon Cognito says the user pool client does not exist
ResourceNotFoundException (HTTP status code 400) returned by InitiateAuth
Cognito looks the app client ID up inside the Region you call.
3 causes, each with a fixBack end
S3 says Access Denied when my Node.js code reads or writes an object
Access Denied
S3 answers AccessDenied when no policy allows the exact action on the exact resource, when something denies it, or when the SDK signs with a different identity than you think.
5 causes, each with a fixBack end
API Gateway gives up on a slow Lambda or Node.js backend
$context.integrationErrorMessage in the access log shows the integration error
API Gateway stops waiting for the backend at its integration timeout: 29 seconds by default on REST APIs, a fixed 30 seconds on HTTP APIs.
4 causes, each with a fix