HTTP 요청을 실행할 수 없습니다(DynamoDB, Java SDK)

TL;DR — Java SDK가 HTTP 응답을 받지 못했습니다. DynamoDB 엔드포인트에 대한 TCP 연결이 실패했습니다. localhost:8000은 DynamoDB Local이 실행되고 있지 않음(또는 다른 포트에 있음)을 의미하며 Docker/SAM 컨테이너 내부에서는 localhost이 사용자 머신이 아닌 _container_이므로 해당 주소에서 에뮬레이터에 연결할 수 없습니다. 에뮬레이터를 시작하고, 엔드포인트를 수정하고, 컨테이너에서 호스트에 연결할 수 있는 주소를 사용하세요.

무엇을 의미하는가

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`](/dynamodb-errors/could-not-connect-to-endpoint)에 해당하는 Java입니다.

왜 발생하는가

DynamoDB Local이 실행되고 있지 않습니다 — 시작되지 않았거나, 시작 시 충돌이 발생했거나(native library, port conflict), 마지막 터미널에서 종료되었습니다.
잘못된 포트 또는 구성표 — 로컬 기본값은 일반 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), 작성 서비스 이름(http://dynamodb:8000)을 사용하거나 두 컨테이너를 동일한 Docker 네트워크에 연결하세요. sam local의 경우 에뮬레이터 컨테이너와 공유되는 --docker-network를 전달합니다.
실제 AWS에 대해 지역 호스트 이름이 올바른지 확인하고 네트워크에 필요한 경우 SDK의 프록시 설정을 구성합니다. 프라이빗 서브넷에서 DynamoDB 게이트웨이 VPC 엔드포인트 또는 NAT 경로를 추가합니다.
HTTP와 HTTPS를 일치시킵니다. DynamoDB Local은 포트 8000에서 일반 HTTP를 사용합니다. — https:// 엔드포인트가 연결을 거부합니다.

DynoTable에서 보기

Java HTTP 클라이언트를 맹목적으로 디버깅하는 대신 DynoTable에서 로컬에 연결 — 설정 → 프로필 → 프로필 추가, 엔드포인트 http://localhost:8000 설정, 지역 문자열 선택 및 연결 테스트 실행. DynoTable은 SDK가 듣기 전에 에뮬레이터가 듣고 있는지 확인합니다.

실제 AWS의 경우 리전 엔드포인트에도 동일한 프로필 흐름이 적용됩니다. Connect to AWS 및 Install을 참조하세요. 연결되면 ⌘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 = 클라이언트 측 문제, 예: 사용할 수 있는 네트워크 연결 없음)
Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (기본 포트 8000, 실행 명령, Docker 예)
DynamoDB local usage notes — AWS DynamoDB Developer Guide(로컬 끝점 http://localhost:8000 설정)
docker run --add-host — Docker CLI reference (컨테이너-호스트 연결의 경우 host.docker.internal / host-gateway)

위에 링크된 공식 AWS 문서를 기준으로 2026년 7월 13일에 마지막으로 확인되었습니다.