Unable to execute HTTP request (DynamoDB, Java SDK)

In breve — L'SDK Java non ha mai ottenuto una risposta HTTP: la connessione TCP all'endpoint DynamoDB è fallita. Verso localhost:8000 significa che DynamoDB Local non è in esecuzione (o è su un'altra porta) — e all'interno di container Docker/SAM, localhost è il container, non la tua macchina, quindi l'emulatore è irraggiungibile a quell'indirizzo. Avvia l'emulatore, correggi l'endpoint, e usa un indirizzo raggiungibile dall'host dai container.

Cosa significa

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

SdkClientException (v1: AmazonClientException) è il wrapper di fallimento lato client dell'SDK — la richiesta è morta prima che DynamoDB la vedesse. La causa annidata ti dice quale passo di rete è fallito: Connection refused (nulla in ascolto), connect timed out (nessuna route/firewall), o UnknownHostException (l'hostname non si risolve, spesso una region o un endpoint con refuso). È l'equivalente Java di Could not connect to the endpoint URL di botocore.

Perché accade

DynamoDB Local non è in esecuzione — non è mai stato avviato, è crashato all'avvio (libreria nativa, conflitto di porta), o è uscito con il tuo ultimo terminale.
Porta o schema errati — Local usa di default la 8000 su http semplice; un endpoint https://localhost:8000 o la porta sbagliata rifiuta.
localhost all'interno di un container — codice in esecuzione in Docker/SAM (sam local invoke) chiama il proprio loopback. L'emulatore sul tuo host (o in un container fratello) non è lì.
Verso AWS reale: nessun percorso di rete — proxy aziendale non configurato sul client HTTP dell'SDK, VPC senza una route/endpoint per DynamoDB, o una region con refuso che produce un hostname inesistente.

Come correggerlo

Conferma che qualcosa sia in ascolto dove stai chiamando:
```
curl http://localhost:8000    # DynamoDB Local answers 400 with an AmazonDynamoDBv2 body
```
Se fallisce, avvia l'emulatore (java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar o docker run -p 8000:8000 amazon/dynamodb-local).

Punta il client all'endpoint giusto (SDK v2):

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

Da un container, non chiamare localhost — usa host.docker.internal:8000 (Docker Desktop), il nome del servizio compose (http://dynamodb:8000), o collega entrambi i container alla stessa rete Docker. Per sam local, passa un --docker-network condiviso con il container dell'emulatore.
Verso AWS reale, verifica che l'hostname della region sia corretto e configura le impostazioni proxy dell'SDK se la tua rete ne richiede uno; dalle subnet private, aggiungi un endpoint gateway VPC per DynamoDB o una route NAT.

Una volta che l'endpoint risponde, verifica che i dati fluiscano end-to-end — l'app desktop DynoTable si connette sia a DynamoDB Local sia ad AWS reale, così puoi vedere le tabelle che il tuo codice Java sta (o non sta) contattando. Stai costruendo la richiesta stessa? Il DynamoDB Expression Builder genera condizioni sulla chiave corrette e valori tipizzati.

Errori correlati

Could not connect to the endpoint URL (boto3) — il gemello Python.
Could not connect to DynamoDB Local (ECONNREFUSED) — il gemello Node.js.
DynamoDB Local port 8000 in use
Impara: Running DynamoDB Local · Connect to Local & LocalStack

References

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)

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.