"Could not connect to DynamoDB Local" (ECONNREFUSED): no se pudo conectar a DynamoDB Local

TL;DR: No hay nada escuchando donde tu client está marcando. Confirme que DynamoDB Local realmente se esté ejecutando en el puerto esperado y que el endpoint de su client apunte a http://localhost:8000, no es un AWS.

Qué significa

Error: connect ECONNREFUSED 127.0.0.1:8000

La conexión TCP fue rechazada: el emulador no está levantado en ese host/puerto, o el cliente apunta a un sitio donde no hay nada escuchando.

Por qué ocurre

DynamoDB Local no está en marcha — nunca arrancó, se cayó, o se apagó (mira el error de arranque de proceso).
Puerto incorrecto — Local está en 8000 pero el cliente marca 8080 (o el contenedor mapea un puerto de host distinto).
Sin endpoint definido — sin él, el SDK habla con AWS real, no con localhost (lo que luego aparece como errores de autenticación/región, o rechazado si sobrescribiste el host).
Red de Docker — desde otro contenedor, localhost es ese contenedor, no el host. Usa el nombre del servicio / el gateway del host.
Peculiaridades de resolución de localhost vs 127.0.0.1 (IPv6 ::1).

Configuraciones habituales

Configuración	Endpoint	Trampa
Docker por defecto	`http://localhost:8000`	El contenedor debe publicar `-p 8000:8000`
Puerto personalizado	`http://localhost:8001`	Haz coincidir `-port 8001` en el jar y el cliente
Servicio de compose	`http://dynamodb:8000`	Desde otro contenedor — no `localhost`
AWS real por error	`https://dynamodb.<region>.amazonaws.com`	Quita `endpoint` cuando quieras la nube

En Windows, WSL y el host a veces no se ponen de acuerdo sobre qué proceso posee localhost:8000 — si curl funciona en WSL pero Node en el host recibe ECONNREFUSED, apunta el cliente del host a 127.0.0.1 de forma explícita o ejecuta Local donde se ejecuta el cliente.

El Test Connection de DynoTable sobre un perfil Local es la comprobación más rápida de que algo responde en el endpoint que configuraste — falla con el mismo socket rechazado cuando Local está caído.

Cómo solucionarlo

Confirma que está escuchando:

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

Define el endpoint explícitamente en el cliente:

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

Haz coincidir el puerto que el emulador realmente enlazó (y el mapeo -p host:container de Docker).
¿Entre contenedores? Usa el nombre del contenedor/servicio (p. ej. http://dynamodb-local:8000) o host.docker.internal, no localhost (host.docker.internal se resuelve automáticamente en Docker Desktop; en Linux Docker Engine añade --add-host host.docker.internal:host-gateway).

Workbench de DynoTable

Instala DynoTable y luego ve a Settings → Profiles → Add Profile con el endpoint http://localhost:8000. Pulsa ⌘P para cambiar al perfil Local en cuanto curl http://localhost:8000 funcione. El punto de credenciales debe seguir verde mientras Local esté levantado; si se pone rojo con errores de conexión, el puerto o el endpoint del perfil no coinciden con donde escucha el emulador. Usa el conversor de DynamoDB JSON para cargar fixtures cuando Local sea alcanzable.

Si curl http://localhost:8000 falla, el emulador no está en marcha — arranca Docker o el jar primero (No se puede iniciar el proceso de DynamoDB Local). Cuando el puerto es incorrecto pero algo sí está escuchando, puedes ver un error HTTP genérico en lugar de ECONNREFUSED; haz coincidir el endpoint del perfil con lo que reporte lsof -i :8000. Guía: Conectar a DynamoDB Local y LocalStack.

Errores relacionados

Fuentes

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)