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

Typical setups

Setup	Endpoint	Gotcha
Docker default	`http://localhost:8000`	Container must publish `-p 8000:8000`
Custom port	`http://localhost:8001`	Match `-port 8001` on the jar and the client
Compose service	`http://dynamodb:8000`	From another container — not `localhost`
Real AWS by mistake	`https://dynamodb.<region>.amazonaws.com`	Drop `endpoint` when you mean cloud

On Windows, WSL and the host sometimes disagree about which process owns localhost:8000 — if curl works in WSL but Node on the host gets ECONNREFUSED, point the host client at 127.0.0.1 explicitly or run Local where the client runs.

DynoTable's Test Connection on a Local profile is the fastest check that something answers on the endpoint you configured — it fails with the same refused socket when Local is down.

How to fix it

Confirm it's listening:

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

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'}
});

Match the port the emulator actually bound (and the Docker -p host:container mapping).
Cross-container? Use the container/service name (e.g. http://dynamodb-local:8000) or host.docker.internal, not localhost (host.docker.internal resolves automatically in Docker Desktop; on Linux Docker Engine add --add-host host.docker.internal:host-gateway).

DynoTable workbench

Install DynoTable, then Settings → Profiles → Add Profile with endpoint http://localhost:8000. Press ⌘P to switch to the Local profile once curl http://localhost:8000 succeeds. The credential dot should stay green while Local is up; if it flips red with connection errors, the port or endpoint in the profile does not match where the emulator listens. Use the DynamoDB JSON converter to load fixtures after Local is reachable.

If curl http://localhost:8000 fails, the emulator is not running — start Docker or the jar first (Unable to start DynamoDB Local process). When the port is wrong but something is listening, you may see a generic HTTP error instead of ECONNREFUSED; match the profile endpoint to whatever lsof -i :8000 reports. Guide: Connect to DynamoDB Local & LocalStack.

Sources

Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000, launch command, Docker run/compose examples)
DynamoDB local usage notes — AWS DynamoDB Developer Guide (local endpoint http://localhost:8000; SDKs require an access key + region value)
amazon/dynamodb-local — Docker Hub (official image, docker run -p 8000:8000 amazon/dynamodb-local)
docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway for container-to-host connections)