Could not connect to the endpoint URL (DynamoDB)

TL;DR — botocore couldn't open a connection to the DynamoDB endpoint it resolved. Almost always a wrong --endpoint-url, DynamoDB Local not running, a bad/typo'd region producing a nonexistent hostname, or no network path (offline, VPC, security group). Point at a reachable endpoint and confirm something is listening.

What it means

botocore.exceptions.EndpointConnectionError: Could not connect to the
endpoint URL: "http://localhost:8000/"

# what the engine actually returns, reproduced against Amazon DynamoDB (live service, us-east-1):
connect ECONNREFUSED 127.0.0.1:9

boto3/botocore builds the DynamoDB endpoint URL from the region (or your explicit endpoint_url) and then fails to establish a TCP/HTTP connection to it. Unlike an auth or validation error, the request never reached a running service. It surfaces both against DynamoDB Local (emulator down / wrong port) and real AWS (bad region hostname or blocked network).

Why it happens

• DynamoDB Local isn't running — you passed --endpoint-url http://localhost:8000 but the emulator isn't up on that port (see connection refused).
• Wrong endpoint URL — a typo, wrong port, or https where the local emulator serves http.
• Bad region — a misspelled region (us-east-11) resolves to a hostname that doesn't exist, so the connection can't be made.
• No network path — offline, or DynamoDB traffic blocked by a VPC endpoint, security group, or network ACL.
• Cross-container / cross-host — from inside Docker, localhost is the container itself, not the host or the DynamoDB Local service.

How to fix it

1. Confirm what's listening at the endpoint:

   curl http://localhost:8000    # DynamoDB Local answers with a small response

   CopyCopied
2. Fix the endpoint URL — correct host, port (8000 by default), and scheme (http for Local).
3. Check the region spelling for real AWS, and make sure you have a network route (VPC endpoint / security group rules allow DynamoDB).
4. In Docker, use the compose service name or host.docker.internal instead of localhost (host.docker.internal resolves automatically in Docker Desktop; on Linux Docker Engine add --add-host host.docker.internal:host-gateway).
5. Talking to real AWS? Drop the --endpoint-url override entirely and let botocore build the correct regional endpoint.

Point DynoTable at Local

DynoTable validates connectivity with Test Connection on each profile in Settings → Profiles (Connect an AWS account). For DynamoDB Local, set endpoint http://localhost:8000 (or :4566 for LocalStack) with placeholder credentials — the same values the CLI needs. Press ⌘P to switch profiles when your app uses a different port than DynoTable. Guide: Connect to DynamoDB Local & LocalStack.

Against real AWS, a typo in the region string produces a hostname that does not resolve — the same EndpointConnectionError shape as an unreachable Local port. Confirm with aws sts get-caller-identity on the profile before debugging DynamoDB-specific settings.

Related errors

• Could not connect to DynamoDB Local (ECONNREFUSED) — the Node/JS equivalent of a refused local connection.
• Missing region in config — no region, so the SDK can't build an endpoint at all.
• Learn: Running DynamoDB Local · Connecting to DynamoDB Local / LocalStack

Sources

• Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000, dummy credentials, --endpoint-url)
• DynamoDB local usage notes — AWS DynamoDB Developer Guide (setting the local endpoint; --endpoint-url required on every CLI command)
• Error handling — Boto3 Developer Guide (EndpointConnectionError as a client-side botocore exception)
• docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway for container-to-host connections)