Unable to execute HTTP request (DynamoDB, Java SDK)

TL;DR — Java SDK は HTTP レスポンスをまったく受け取れませんでした。DynamoDB エンドポイントへの TCP 接続が失敗したのです。localhost:8000 に対しては、DynamoDB Local が実行されていない（または別のポートにある）ことを意味します。そして Docker/SAM コンテナ内では、localhost は コンテナ でありあなたのマシンではないため、そのアドレスではエミュレータに到達できません。エミュレータを起動し、エンドポイントを修正し、コンテナからはホスト到達可能なアドレスを使ってください。

意味

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

SdkClientException（v1: AmazonClientException）は SDK のクライアント側の失敗ラッパーです。リクエストは DynamoDB が見る前に死にました。ネストされた原因が、どのネットワークステップが失敗したかを教えてくれます: Connection refused（何もリッスンしていない）、connect timed out（ルート/ファイアウォールがない）、UnknownHostException（ホスト名が解決しない、しばしばタイプミスのリージョンやエンドポイント）。これは botocore の Could not connect to the endpoint URL の Java 版です。

発生する理由

DynamoDB Local が実行されていない — 起動しなかった、起動時にクラッシュした（ネイティブライブラリ、ポート競合）、または最後のターミナルとともに終了した。
誤ったポートまたはスキーム — Local はデフォルトで素の http 上の 8000。https://localhost:8000 や誤ったポートのエンドポイントは拒否します。
コンテナ内の localhost — Docker/SAM（sam local invoke）で実行されるコードは 自身の ループバックをダイヤルします。ホスト上（または兄弟コンテナ内）のエミュレータはそこにありません。
本物の AWS に対して: ネットワーク経路がない — SDK の HTTP クライアントに企業プロキシが設定されていない、DynamoDB へのルート/エンドポイントのない VPC、またはタイプミスのリージョンが存在しないホスト名を生む。

修正方法

ダイヤルする先で 何かがリッスンしているか確認します:
```
curl http://localhost:8000    # DynamoDB Local answers 400 with an AmazonDynamoDBv2 body
```
失敗する場合はエミュレータを起動します（java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar または docker run -p 8000:8000 amazon/dynamodb-local）。

クライアントを正しいエンドポイントに向けます（v2 SDK）:

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

コンテナからは localhost をダイヤルしないでください — host.docker.internal:8000（Docker Desktop）、compose のサービス名（http://dynamodb:8000）を使うか、両方のコンテナを同じ Docker ネットワークにアタッチします。sam local では、エミュレータコンテナと共有する --docker-network を渡します。
本物の AWS に対しては、リージョンのホスト名が正しいか検証し、ネットワークが必要なら SDK のプロキシ設定を構成します。プライベートサブネットからは、DynamoDB ゲートウェイ VPC エンドポイントまたは NAT ルートを追加します。

エンドポイントが応答したら、データが端から端まで流れることを検証します。DynoTable デスクトップアプリは DynamoDB Local と本物の AWS の両方に接続するため、Java コードがアクセスしている（またはしていない）テーブルを見ることができます。リクエスト自体を組み立てますか？DynamoDB Expression Builder は正しいキー条件と型付き値を生成します。

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)

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Unable to execute HTTP request (DynamoDB, Java SDK)

意味

発生する理由

修正方法

関連するエラー

References