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 預設在 8000 上使用純 http；https://localhost:8000 的端點或錯誤的埠會拒絕連線。
容器內部的 localhost——執行在 Docker/SAM（sam local invoke）中的程式碼撥的是它_自己_的環回地址。你主機上（或在一個兄弟容器中）的模擬器並不在那裡。
對著真實 AWS：沒有網路路徑——SDK 的 HTTP 用戶端上沒有配置公司代理、VPC 沒有到 DynamoDB 的路由/端點，或者拼錯的區域產生了一個不存在的主機名。

如何修正

確認你撥號的地方有東西在監聽：
```
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 會生成正確的鍵條件和帶型別的值。

在 DynoTable 中檢視

從 DynoTable 連線到本地，而不是盲目地除錯 Java HTTP 用戶端 — Settings → Profiles → 新增 Profile，設定端點 http://localhost:8000，選擇任何區域字串，然後執行 測試連線*。 DynoTable 確認模擬器在你的 SDK 之前正在監聽。對於實際AWS，相同的設定檔案流適用於區域端點。參見連線 AWS和安裝。連線後，使用 ⌘K 開啟表格。連線確認後，在Query Builder中發出原型請求。

來源

Handling errors in the AWS SDK for Java 2.x（2026-07-13 驗證）
Deploying DynamoDB locally（2026-07-13 驗證）

參考資料

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 官方文件。