Unable to execute HTTP request (DynamoDB, Java SDK)

TL;DR — Das Java-SDK hat nie eine HTTP-Antwort erhalten: Die TCP-Verbindung zum DynamoDB-Endpoint ist fehlgeschlagen. Gegen localhost:8000 bedeutet das, dass DynamoDB Local nicht läuft (oder auf einem anderen Port ist) — und innerhalb von Docker/SAM-Containern ist localhost der Container, nicht deine Maschine, sodass der Emulator unter dieser Adresse unerreichbar ist. Starte den Emulator, korrigiere den Endpoint und nutze aus Containern eine host-erreichbare Adresse.

Was es bedeutet

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

SdkClientException (v1: AmazonClientException) ist der clientseitige Fehler-Wrapper des SDK — die Anfrage starb, bevor DynamoDB sie je sah. Die verschachtelte Ursache sagt dir, welcher Netzwerkschritt fehlschlug: Connection refused (nichts lauscht), connect timed out (keine Route/Firewall) oder UnknownHostException (der Hostname löst nicht auf, oft eine vertippte Region oder ein vertippter Endpoint). Es ist das Java-Äquivalent zu botocores Could not connect to the endpoint URL.

Warum es passiert

• DynamoDB Local läuft nicht — es wurde nie gestartet, ist beim Start abgestürzt (native Bibliothek, Portkonflikt) oder hat sich mit deinem letzten Terminal beendet.
• Falscher Port oder falsches Schema — Local defaultet auf 8000 über schlichtes http; ein Endpoint von https://localhost:8000 oder der falsche Port wird abgelehnt.
• localhost innerhalb eines Containers — Code, der in Docker/SAM (sam local invoke) läuft, wählt sein eigenes Loopback. Der Emulator auf deinem Host (oder in einem Geschwister-Container) ist dort nicht.
• Gegen echtes AWS: kein Netzwerkpfad — Firmenproxy nicht auf dem HTTP-Client des SDK konfiguriert, VPC ohne Route/Endpoint für DynamoDB, oder eine vertippte Region, die einen nicht existierenden Hostnamen erzeugt.

So behebst du es

1. Bestätige, dass etwas lauscht, wo du anwählst:

   curl http://localhost:8000    # DynamoDB Local answers 400 with an AmazonDynamoDBv2 body

   Wenn das fehlschlägt, starte den Emulator (java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar oder docker run -p 8000:8000 amazon/dynamodb-local).

2. Richte den Client auf den richtigen Endpoint (v2-SDK):

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

3. Wähle aus einem Container nicht localhost — nutze host.docker.internal:8000 (Docker Desktop), den Compose-Service-Namen (http://dynamodb:8000) oder hänge beide Container an dasselbe Docker-Netzwerk. Für sam local übergib ein --docker-network, das mit dem Emulator-Container geteilt wird.

4. Gegen echtes AWS verifiziere, dass der Region-Hostname stimmt, und konfiguriere die Proxy-Einstellungen des SDK, falls dein Netzwerk einen verlangt; aus privaten Subnetzen füge einen DynamoDB-Gateway-VPC-Endpoint oder eine NAT-Route hinzu.

Sobald der Endpoint antwortet, verifiziere, dass Daten durchgängig fließen — die DynoTable-Desktop-App verbindet sich sowohl mit DynamoDB Local als auch mit echtem AWS, sodass du die Tabellen sehen kannst, die dein Java-Code trifft (oder nicht trifft). Die Anfrage selbst bauen? Der DynamoDB Expression Builder erzeugt korrekte Key-Conditions und typisierte Werte.

Verwandte Fehler

• Could not connect to the endpoint URL (boto3) — der Python-Zwilling.
• Could not connect to DynamoDB Local (ECONNREFUSED) — der Node.js-Zwilling.
• DynamoDB Local port 8000 in use
• Learn: 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)

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.