DynamoDB Local "Unable to execute HTTP request: Connection refused" on 8000 in CI

By Kaveh Alemi·Latchkey

DynamoDB Local listens on port 8000 by default. The AWS SDK fails with "Unable to execute HTTP request: Connect to ... 8000 ... failed: Connection refused" when it calls the endpoint before the container is ready.

What this error means

An SDK call fails with "Unable to execute HTTP request: Connection refused (Connection refused)" pointing at the local endpoint URL, clearing once the container is up.

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

Common causes

The local container has not started listening

DynamoDBLocal takes a moment to start its HTTP server on 8000; SDK calls before that are refused.

No readiness wait before the test

The job invokes the SDK as soon as the container exists rather than waiting for the endpoint to answer.

How to fix it

Wait for the endpoint with a list-tables probe

1. Loop aws dynamodb list-tables against the local endpoint.
2. Treat success as readiness.
3. Run tests only after it returns.

until aws dynamodb list-tables --endpoint-url http://127.0.0.1:8000 \
  --region us-east-1 >/dev/null 2>&1; do
  echo "waiting for dynamodb local"; sleep 2
done

Health-check the container port

Gate dependent steps on the endpoint answering before running.

services:
  dynamodb:
    image: amazon/dynamodb-local:latest
    ports: ['8000:8000']
    options: --health-cmd "curl -f http://localhost:8000/ || exit 1" --health-retries 10

How to prevent it

• Probe the local endpoint before issuing SDK calls.
• Point the SDK at the explicit --endpoint-url.
• Allow a few retries for container startup.

Frequently asked questions

Related guides

References

• GitHub Actions documentation