Unable to execute HTTP request (DynamoDB, Java SDK)

요약 — 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)

공식 AWS 문서(위 링크)를 기준으로 2026-07-13에 마지막으로 검증되었습니다.

Unable to execute HTTP request (DynamoDB, Java SDK)

무엇을 의미하나요

왜 발생하나요

어떻게 고치나요

관련 오류

References