Could not connect to DynamoDB Local (ECONNREFUSED)

TL;DR — Nothing is listening where your client is dialing. Confirm DynamoDB Local is actually running on the port you expect, and that your client's endpoint points at http://localhost:8000 — not real AWS.

What it means

Error: connect ECONNREFUSED 127.0.0.1:8000

The TCP connection was refused: the emulator isn't up on that host/port, or the client is pointed somewhere nothing is listening.

Why it happens

• DynamoDB Local isn't running — it never started, crashed, or was shut down (see the start-process error).
• Wrong port — Local is on 8000 but the client dials 8080 (or the container maps a different host port).
• No endpoint set — without it the SDK talks to real AWS, not localhost (which then surfaces as auth/region errors, or refused if you overrode the host).
• Docker networking — from another container, localhost is that container, not the host. Use the service name / host gateway.
• localhost vs 127.0.0.1 resolution quirks (IPv6 ::1).

How to fix it

1. Confirm it's listening:

   curl http://localhost:8000        # DynamoDB Local returns a small response
   lsof -i :8000                     # something should own the port

2. Set the endpoint explicitly on the client:

   import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
   const client = new DynamoDBClient({
     region: 'local',
     endpoint: 'http://localhost:8000',
     credentials: {accessKeyId: 'local', secretAccessKey: 'local'}
   });

3. Match the port the emulator actually bound (and the Docker -p host:container mapping).
4. Cross-container? Use the container/service name (e.g. http://dynamodb-local:8000) or host.docker.internal, not localhost.

Related errors

• Unable to start DynamoDB Local process
• Missing region in config
• Learn: Running DynamoDB Local · Connecting to DynamoDB Local / LocalStack