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

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).

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();

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.
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.
Match HTTP vs HTTPS. DynamoDB Local speaks plain HTTP on port 8000 — an https:// endpoint refuses the connection.

See it in DynoTable

Connect to Local from DynoTable instead of debugging Java HTTP clients blindly — Settings → Profiles → Add Profile, set endpoint http://localhost:8000, pick any region string, and run Test Connection. DynoTable confirms the emulator is listening before your SDK does.

For real AWS, the same profile flow applies with the regional endpoint. See Connect to AWS and Install. Once connected, open tables with ⌘K. Prototype requests in the Query Builder after connectivity is confirmed.

Sources

Handling errors in the AWS SDK for Java 2.x (verified 2026-07-13)
Deploying DynamoDB locally (verified 2026-07-13)

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.