Could not connect to DynamoDB Local (ECONNREFUSED)

En bref — Rien n'écoute là où ton client compose. Confirme que DynamoDB Local tourne réellement sur le port que tu attends, et que l'endpoint de ton client pointe vers http://localhost:8000 — pas le vrai AWS.

Ce que ça signifie

Error: connect ECONNREFUSED 127.0.0.1:8000

La connexion TCP a été refusée : l'émulateur n'est pas actif sur cet hôte/port, ou le client est pointé quelque part où rien n'écoute.

Pourquoi ça arrive

DynamoDB Local n'est pas démarré — il n'a jamais démarré, a planté, ou a été arrêté (voir l'erreur de démarrage de processus).
Mauvais port — Local est sur 8000 mais le client compose 8080 (ou le conteneur mappe un port hôte différent).
Aucun endpoint défini — sans lui, le SDK parle au vrai AWS, pas à localhost (ce qui apparaît ensuite comme des erreurs d'auth/région, ou refusé si tu as surchargé l'hôte).
Réseau Docker — depuis un autre conteneur, localhost est ce conteneur, pas l'hôte. Utilise le nom du service / la passerelle hôte.
Bizarreries de résolution localhost vs 127.0.0.1 (IPv6 ::1).

Configurations typiques

Setup	Endpoint	Piège
Docker par défaut	`http://localhost:8000`	Le conteneur doit publier `-p 8000:8000`
Port personnalisé	`http://localhost:8001`	Faire matcher `-port 8001` sur le jar et le client
Service Compose	`http://dynamodb:8000`	Depuis un autre conteneur — pas `localhost`
Vrai AWS par erreur	`https://dynamodb.<region>.amazonaws.com`	Retire `endpoint` quand tu veux le cloud

Sous Windows, WSL et l'hôte ne sont parfois pas d'accord sur quel processus possède localhost:8000 — si curl marche dans WSL mais que Node sur l'hôte obtient ECONNREFUSED, pointe le client hôte explicitement vers 127.0.0.1 ou lance Local là où le client tourne.

Test Connection de DynoTable sur un profil Local est le check le plus rapide qu'une chose réponde sur l'endpoint que tu as configuré — il échoue avec le même socket refusé quand Local est down.

Comment le corriger

Confirme qu'il écoute :

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

Définis l'endpoint explicitement sur le client :

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

Fais correspondre le port que l'émulateur a réellement lié (et le mappage Docker -p host:container).
Cross-conteneur ? Utilise le nom du conteneur/service (p. ex. http://dynamodb-local:8000) ou host.docker.internal, pas localhost (host.docker.internal se résout automatiquement dans Docker Desktop ; sur Linux Docker Engine, ajoute --add-host host.docker.internal:host-gateway).

Workbench DynoTable

Installe DynoTable, puis Settings → Profiles → Add Profile avec l'endpoint http://localhost:8000. Appuie sur ⌘P pour basculer vers le profil Local une fois que curl http://localhost:8000 réussit. Le point d'identifiants devrait rester vert tant que Local est up ; s'il passe au rouge avec des erreurs de connexion, le port ou l'endpoint du profil ne match pas là où l'émulateur écoute. Utilise le convertisseur DynamoDB JSON pour charger des fixtures après que Local soit joignable.

Si curl http://localhost:8000 échoue, l'émulateur ne tourne pas — démarre Docker ou le jar d'abord (Unable to start DynamoDB Local process). Quand le port est faux mais que quelque chose écoute, tu peux voir une erreur HTTP générique au lieu de ECONNREFUSED ; fais matcher l'endpoint du profil avec ce que lsof -i :8000 rapporte. Guide : Se connecter à DynamoDB Local & LocalStack.

Erreurs liées

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)

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.