Could not connect to DynamoDB Local (ECONNREFUSED)

TL;DR — Nada está escutando onde seu cliente está discando. Confirme que o DynamoDB Local está de fato rodando na porta que você espera, e que o endpoint do seu cliente aponta para http://localhost:8000 — não para a AWS real.

O que significa

Error: connect ECONNREFUSED 127.0.0.1:8000

A conexão TCP foi recusada: o emulador não está no ar naquele host/porta, ou o cliente está apontado para algum lugar onde nada está escutando.

Por que isso acontece

• O DynamoDB Local não está rodando — ele nunca iniciou, travou ou foi encerrado (veja o erro de start-process).
• Porta errada — o Local está na 8000 mas o cliente disca 8080 (ou o contêiner mapeia uma porta de host diferente).
• Nenhum endpoint definido — sem ele o SDK conversa com a AWS real, não com o localhost (o que depois aparece como erros de autenticação/region, ou recusado se você sobrescreveu o host).
• Rede do Docker — de outro contêiner, localhost é aquele contêiner, não o host. Use o nome do serviço / gateway do host.
• Peculiaridades de resolução localhost vs 127.0.0.1 (IPv6 ::1).

Configurações típicas

No Windows, o WSL e o host às vezes discordam sobre qual processo é dono de localhost:8000 — se o curl funciona no WSL mas o Node no host recebe ECONNREFUSED, aponte o cliente do host explicitamente para 127.0.0.1 ou rode o Local onde o cliente roda.

O Testar conexão do DynoTable em um perfil Local é a checagem mais rápida de que algo responde no endpoint que você configurou — ele falha com o mesmo socket recusado quando o Local está fora do ar.

Como corrigir

1. Confirme que está escutando:

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

   CopiarCopiado
2. Defina o endpoint explicitamente no cliente:

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

   CopiarCopiado
3. Confira a porta que o emulador realmente vinculou (e o mapeamento -p host:container do Docker).
4. Entre contêineres? Use o nome do contêiner/serviço (por exemplo, http://dynamodb-local:8000) ou host.docker.internal, não localhost (host.docker.internal resolve automaticamente no Docker Desktop; no Docker Engine em Linux, adicione --add-host host.docker.internal:host-gateway).

Workbench do DynoTable

Instale o DynoTable, depois Configurações → Perfis → Adicionar perfil com o endpoint http://localhost:8000. Pressione ⌘P para trocar para o perfil Local assim que curl http://localhost:8000 responder. O ponto de credencial deve permanecer verde enquanto o Local estiver no ar; se ele ficar vermelho com erros de conexão, a porta ou o endpoint do perfil não corresponde a onde o emulador escuta. Use o conversor de DynamoDB JSON para carregar fixtures depois que o Local estiver acessível.

Se curl http://localhost:8000 falhar, o emulador não está rodando — inicie primeiro o Docker ou o jar (Não é possível iniciar o processo local do DynamoDB). Quando a porta está errada mas algo está escutando, você pode ver um erro HTTP genérico em vez de ECONNREFUSED; alinhe o endpoint do perfil ao que o lsof -i :8000 reportar. Guia: Conecte-se ao DynamoDB Local e LocalStack.

Erros relacionados

• Não é possível iniciar o processo local do DynamoDB
• Região ausente na configuração
• Aprenda: Executando DynamoDB Local · Conectar ao Local e LocalStack

Fontes

• Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (porta padrão 8000, comando de inicialização, exemplos de docker run/compose)
• DynamoDB local usage notes — AWS DynamoDB Developer Guide (endpoint local http://localhost:8000; os SDKs exigem uma access key + um valor de region)
• amazon/dynamodb-local — Docker Hub (imagem oficial, docker run -p 8000:8000 amazon/dynamodb-local)
• docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway para conexões contêiner-para-host)