Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

Node.js S3 client cannot resolve my-bucket.localhost on LocalStack

Errorgetaddrinfo ENOTFOUND my-bucket.localhost

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

  • Applies to Node.js 22, AWS SDK for JavaScript v3, LocalStack S3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

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

    1. 1The failing host is <bucket>.localhost and your endpoint is http://localhost:4566The S3 client uses virtual-hosted addressing against a bare localhost endpointFix
    2. 2You 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. 3The error appears from inside Docker Compose, or the bucket name contains periodsThe app runs in another container, or the bucket name has dotsFix

What does the error look like?

  • getaddrinfo ENOTFOUND my-bucket.localhost
  • Error: 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 ls

Confirmed by docs.localstack.cloud

Did this fix it?

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_URL

2Fix

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

3Verify

Create and list a bucket with the same environment.

aws s3 mb s3://my-bucket
aws s3 ls

Confirmed by docs.localstack.cloud

Did this fix it?

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

2Fix

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

Did this fix it?

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:

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 fix

Back 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

Next step

Want this handled for good?

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