Unable to execute HTTP request (DynamoDB, Java SDK)

TL;DR — O SDK Java nunca recebeu uma resposta HTTP: a conexão TCP com o endpoint do DynamoDB falhou. Contra localhost:8000 isso significa que o DynamoDB Local não está rodando (ou está em outra porta) — e dentro de contêineres Docker/SAM, localhost é o contêiner, não sua máquina, então o emulador é inalcançável naquele endereço. Inicie o emulador, corrija o endpoint e use um endereço alcançável pelo host a partir dos contêineres.

O que significa

com.amazonaws.SdkClientException: Unable to execute HTTP request:
Connect to localhost:8000 [localhost/127.0.0.1] failed: Connection refused

SdkClientException (v1: AmazonClientException) é o wrapper de falha do lado do cliente do SDK — a requisição morreu antes de o DynamoDB sequer vê-la. A causa aninhada diz qual passo de rede falhou: Connection refused (nada escutando), connect timed out (sem rota/firewall), ou UnknownHostException (o hostname não resolve, frequentemente uma region ou endpoint com erro de digitação). É o equivalente Java do Could not connect to the endpoint URL do botocore.

Por que acontece

O DynamoDB Local não está rodando — ele nunca foi iniciado, travou na inicialização (biblioteca nativa, conflito de porta), ou saiu com seu último terminal.
Porta ou esquema errado — o Local usa 8000 sobre http puro por padrão; um endpoint de https://localhost:8000 ou a porta errada recusa.
localhost dentro de um contêiner — código rodando em Docker/SAM (sam local invoke) disca seu próprio loopback. O emulador no seu host (ou em um contêiner irmão) não está ali.
Contra a AWS real: nenhuma rota de rede — proxy corporativo não configurado no cliente HTTP do SDK, VPC sem uma rota/endpoint para o DynamoDB, ou uma region com erro de digitação produzindo um hostname inexistente.

Como corrigir

Confirme que algo está escutando onde você está discando:
```
curl http://localhost:8000    # DynamoDB Local answers 400 with an AmazonDynamoDBv2 body
```
Se isso falhar, inicie o emulador (java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar ou docker run -p 8000:8000 amazon/dynamodb-local).

Aponte o cliente para o endpoint certo (SDK v2):

DynamoDbClient client = DynamoDbClient.builder()
    .endpointOverride(URI.create("http://localhost:8000"))
    .region(Region.US_EAST_1)
    .build();

De um contêiner, não disque localhost — use host.docker.internal:8000 (Docker Desktop), o nome do serviço do compose (http://dynamodb:8000), ou anexe ambos os contêineres à mesma rede Docker. Para sam local, passe um --docker-network compartilhado com o contêiner do emulador.
Contra a AWS real, verifique se o hostname da region está correto e configure as opções de proxy do SDK se sua rede exigir uma; de subnets privadas, adicione um DynamoDB gateway VPC endpoint ou rota NAT.

Uma vez que o endpoint responda, verifique se os dados fluem de ponta a ponta — o app desktop DynoTable conecta-se tanto ao DynamoDB Local quanto à AWS real, para que você possa ver as tabelas que seu código Java está (ou não está) acessando. Construindo a própria requisição? O DynamoDB Expression Builder gera condições de chave corretas e valores tipados.

Erros relacionados

Could not connect to the endpoint URL (boto3) — o gêmeo Python.
Could not connect to DynamoDB Local (ECONNREFUSED) — o gêmeo Node.js.
DynamoDB Local port 8000 in use
Aprenda: Running DynamoDB Local · Connect to Local & LocalStack

Referências

Handling errors in the AWS SDK for Java 2.x — Developer Guide (SdkClientException = a client-side problem, e.g. no network connection available)
Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000, launch command, Docker examples)
DynamoDB local usage notes — AWS DynamoDB Developer Guide (setting the local endpoint http://localhost:8000)
docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway for container-to-host connections)

Verificado pela última vez em 2026-07-13 contra a documentação oficial da AWS vinculada acima.