Unable to execute HTTP request (DynamoDB, Java SDK)

TL;DR — The Java SDK never got an HTTP response: the TCP connection to the DynamoDB endpoint failed. Against localhost:8000 that means DynamoDB Local isn't running (or is on another port) — and inside Docker/SAM containers, localhost is the container, not your machine, so the emulator is unreachable at that address. Start the emulator, fix the endpoint, and use a host-reachable address from containers.

What it means

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

SdkClientException (v1: AmazonClientException) is the SDK's client-side failure wrapper — the request died before DynamoDB ever saw it. The nested cause tells you which network step failed: Connection refused (nothing listening), connect timed out (no route/firewall), or UnknownHostException (the hostname doesn't resolve, often a typo'd region or endpoint). It's the Java equivalent of botocore's Could not connect to the endpoint URL.

Why it happens

• DynamoDB Local isn't running — it was never started, crashed at startup (native library, port conflict), or exited with your last terminal.
• Wrong port or scheme — Local defaults to 8000 over plain http; an endpoint of https://localhost:8000 or the wrong port refuses.
• localhost inside a container — code running in Docker/SAM (sam local invoke) dials its own loopback. The emulator on your host (or in a sibling container) isn't there.
• Against real AWS: no network path — corporate proxy not configured on the SDK's HTTP client, VPC without a route/endpoint for DynamoDB, or a typo'd region producing a non-existent hostname.

How to fix it

1. Confirm something is listening where you're dialing:

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

   If that fails, start the emulator (java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar or docker run -p 8000:8000 amazon/dynamodb-local).

2. Point the client at the right endpoint (v2 SDK):

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

3. From a container, don't dial localhost — use host.docker.internal:8000 (Docker Desktop), the compose service name (http://dynamodb:8000), or attach both containers to the same Docker network. For sam local, pass a --docker-network shared with the emulator container.

4. Against real AWS, verify the region hostname is right and configure the SDK's proxy settings if your network requires one; from private subnets, add a DynamoDB gateway VPC endpoint or NAT route.

Once the endpoint answers, verify data flows end to end — the DynoTable desktop app connects to both DynamoDB Local and real AWS, so you can see the tables your Java code is (or isn't) hitting. Building the request itself? The DynamoDB Expression Builder generates correct key conditions and typed values.

Related errors

• Could not connect to the endpoint URL (boto3) — the Python twin.
• Could not connect to DynamoDB Local (ECONNREFUSED) — the Node.js twin.
• 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)

Last verified 2026-07-13 against the official AWS documentation linked above.