Could not connect to DynamoDB Local (ECONNREFUSED)

TL;DR — Dort, wo dein Client anklopft, lauscht nichts. Stelle sicher, dass DynamoDB Local wirklich auf dem erwarteten Port läuft und dass der endpoint deines Clients auf http://localhost:8000 zeigt — nicht auf das echte AWS.

Was es bedeutet

Error: connect ECONNREFUSED 127.0.0.1:8000

Die TCP-Verbindung wurde abgelehnt: Der Emulator ist auf diesem Host/Port nicht oben, oder der Client zeigt irgendwohin, wo nichts lauscht.

Warum es passiert

DynamoDB Local läuft nicht — es ist nie gestartet, abgestürzt oder heruntergefahren worden (siehe den Start-Prozess-Fehler).
Falscher Port — Local ist auf 8000, aber der Client wählt 8080 (oder der Container mappt einen anderen Host-Port).
Kein endpoint gesetzt — ohne ihn spricht das SDK mit echtem AWS, nicht mit localhost (was dann als Auth-/Region-Fehler erscheint, oder als Refused, wenn du den Host überschrieben hast).
Docker-Networking — aus einem anderen Container ist localhost dieser Container, nicht der Host. Nutze den Service-Namen / Host-Gateway.
localhost vs. 127.0.0.1 Auflösungs-Eigenheiten (IPv6 ::1).

Typische Setups

Setup	Endpoint	Fallstrick
Docker-Standard	`http://localhost:8000`	Container muss `-p 8000:8000` veröffentlichen
Eigener Port	`http://localhost:8001`	`-port 8001` am JAR und am Client angleichen
Compose-Service	`http://dynamodb:8000`	Aus einem anderen Container — nicht `localhost`
Versehentlich echtes AWS	`https://dynamodb.<region>.amazonaws.com`	`endpoint` weglassen, wenn du die Cloud meinst

Unter Windows sind sich WSL und der Host manchmal uneinig darüber, welcher Prozess localhost:8000 besitzt — funktioniert curl in WSL, während Node auf dem Host ECONNREFUSED bekommt, richte den Host-Client explizit auf 127.0.0.1 aus oder starte Local dort, wo auch der Client läuft.

DynoTables Verbindung testen auf einem Local-Profil ist die schnellste Probe, ob auf dem konfigurierten Endpoint überhaupt etwas antwortet — es scheitert mit demselben abgelehnten Socket, wenn Local unten ist.

So behebst du es

Bestätige, dass es lauscht:

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

Setze den Endpoint explizit am Client:

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

Bringe den Port in Einklang mit dem, an den sich der Emulator tatsächlich gebunden hat (und dem Docker--p host:container-Mapping).
Container-übergreifend? Nutze den Container-/Service-Namen (z. B. http://dynamodb-local:8000) oder host.docker.internal, nicht localhost (host.docker.internal löst in Docker Desktop automatisch auf; auf Linux Docker Engine füge --add-host host.docker.internal:host-gateway hinzu).

DynoTable-Workbench

DynoTable installieren, dann Einstellungen → Profile → Profil hinzufügen mit dem Endpoint http://localhost:8000. Drücke ⌘P, um auf das Local-Profil zu wechseln, sobald curl http://localhost:8000 erfolgreich ist. Der Credential-Punkt sollte grün bleiben, solange Local oben ist; kippt er mit Verbindungsfehlern auf Rot, passen Port oder Endpoint im Profil nicht dorthin, wo der Emulator lauscht. Nutze den DynamoDB JSON Converter, um Fixtures zu laden, sobald Local erreichbar ist.

Schlägt curl http://localhost:8000 fehl, läuft der Emulator nicht — starte zuerst Docker oder das JAR (Unable to start DynamoDB Local process). Wenn der Port falsch ist, aber etwas lauscht, siehst du womöglich einen generischen HTTP-Fehler statt ECONNREFUSED; gleiche den Profil-Endpoint an das an, was lsof -i :8000 meldet. Guide: Connect to DynamoDB Local & LocalStack.

Quellen

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)