Unable to execute HTTP request (DynamoDB, Java SDK)

TL;DR — El SDK de Java nunca recibió una respuesta HTTP: la conexión TCP al endpoint de DynamoDB falló. Contra localhost:8000 eso significa que DynamoDB Local no está en marcha (o está en otro puerto) — y dentro de contenedores Docker/SAM, localhost es el contenedor, no tu máquina, así que el emulador es inalcanzable en esa dirección. Arranca el emulador, corrige el endpoint y usa una dirección alcanzable desde el host en los contenedores.

Qué significa

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

SdkClientException (v1: AmazonClientException) es el envoltorio de fallo del lado del cliente del SDK — la petición murió antes de que DynamoDB llegara a verla. La causa anidada te dice qué paso de red falló: Connection refused (nada escuchando), connect timed out (sin ruta/firewall) o UnknownHostException (el nombre de host no resuelve, a menudo una región o endpoint mal escritos). Es el equivalente en Java del Could not connect to the endpoint URL de botocore.

Por qué ocurre

DynamoDB Local no está en marcha — nunca se arrancó, falló al arrancar (biblioteca nativa, conflicto de puerto), o se cerró con tu última terminal.
Puerto o esquema incorrectos — Local usa por defecto el 8000 sobre http plano; un endpoint de https://localhost:8000 o el puerto equivocado rechaza la conexión.
localhost dentro de un contenedor — el código que corre en Docker/SAM (sam local invoke) marca su propio loopback. El emulador en tu host (o en un contenedor hermano) no está ahí.
Contra AWS real: sin ruta de red — proxy corporativo no configurado en el cliente HTTP del SDK, VPC sin una ruta/endpoint para DynamoDB, o una región mal escrita que produce un nombre de host inexistente.

Cómo solucionarlo

Confirma que algo está escuchando donde estás marcando:
```
curl http://localhost:8000    # DynamoDB Local answers 400 with an AmazonDynamoDBv2 body
```
Si eso falla, arranca el emulador (java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar o docker run -p 8000:8000 amazon/dynamodb-local).

Apunta el cliente al endpoint correcto (SDK v2):

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

Desde un contenedor, no marques localhost — usa host.docker.internal:8000 (Docker Desktop), el nombre del servicio de compose (http://dynamodb:8000), o conecta ambos contenedores a la misma red de Docker. Para sam local, pasa un --docker-network compartido con el contenedor del emulador.
Contra AWS real, verifica que el nombre de host de la región sea correcto y configura los ajustes de proxy del SDK si tu red lo requiere; desde subredes privadas, añade un endpoint de VPC de tipo gateway para DynamoDB o una ruta NAT.

Una vez que el endpoint responda, verifica que los datos fluyan de extremo a extremo — la aplicación de escritorio DynoTable se conecta tanto a DynamoDB Local como a AWS real, para que veas las tablas que tu código Java está (o no está) alcanzando. ¿Construyendo la propia petición? El DynamoDB Expression Builder genera condiciones de clave y valores tipados correctos.

Errores relacionados

Could not connect to the endpoint URL (boto3) — el gemelo en Python.
Could not connect to DynamoDB Local (ECONNREFUSED) — el gemelo en Node.js.
DynamoDB Local port 8000 in use
Aprende: Ejecutar DynamoDB Local · Conectar a Local y LocalStack

Referencias

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)

Verificado por última vez el 2026-07-13 contra la documentación oficial de AWS enlazada arriba.