Could not connect to the endpoint URL (DynamoDB)

TL;DR — botocore が、解決した DynamoDB エンドポイントへの接続を開けませんでした。ほぼ必ず誤った --endpoint-url、DynamoDB Local の未起動、存在しないホスト名を生む誤った/タイプミスのリージョン、またはネットワーク経路の欠如（オフライン、VPC、セキュリティグループ）が原因です。到達可能なエンドポイントを指し、何かがリッスンしていることを確認してください。

意味

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 はリージョン（またはあなたの明示的な endpoint_url）から DynamoDB エンドポイント URL を組み立て、それに対する TCP/HTTP 接続の確立に失敗します。認証や検証エラーとは異なり、リクエストは実行中のサービスに到達していません。これは DynamoDB Local（エミュレータのダウン / 誤ったポート）と 本物の AWS（誤ったリージョンのホスト名やブロックされたネットワーク）の両方で発生します。

発生する理由

DynamoDB Local が実行されていない — --endpoint-url http://localhost:8000 を渡したが、そのポートでエミュレータが起動していない（接続拒否を参照）。
誤ったエンドポイント URL — タイプミス、誤ったポート、あるいはローカルエミュレータが http を提供するのに https。
誤ったリージョン — スペルミスのリージョン（us-east-11）が存在しないホスト名に解決するため、接続できない。
ネットワーク経路がない — オフライン、または VPC エンドポイント、セキュリティグループ、ネットワーク ACL によって DynamoDB トラフィックがブロックされている。
コンテナ間 / ホスト間 — Docker 内部からは localhost はコンテナ自身であり、ホストや DynamoDB Local サービスではありません。

修正方法

エンドポイントで 何がリッスンしているか確認します:
```
curl http://localhost:8000    # DynamoDB Local answers with a small response
```
エンドポイント URL を修正します — 正しいホスト、ポート（デフォルトで 8000）、スキーム（Local では http）。
本物の AWS では リージョンのスペルを確認 し、ネットワークルート（VPC エンドポイント / セキュリティグループのルールが DynamoDB を許可）があることを確かめます。
Docker では、localhost の代わりに compose のサービス名や host.docker.internal を使います（host.docker.internal は Docker Desktop では自動的に解決します。Linux の Docker Engine では --add-host host.docker.internal:host-gateway を追加してください）。
本物の AWS と通信していますか？ --endpoint-url の上書きを完全に外し、botocore に正しいリージョナルエンドポイントを組み立てさせましょう。

DynoTable を Local に向ける

DynoTable は Settings → Profiles の各プロファイルにある Test Connection で疎通を検証します（AWS アカウントに接続する）。DynamoDB Local なら、エンドポイントに http://localhost:8000（LocalStack なら :4566）を、認証情報にはプレースホルダーを設定します — CLI が必要とするのと同じ値です。アプリが DynoTable とは別のポートを使っている場合は、⌘P でプロファイルを切り替えてください。ガイド: DynamoDB Local と LocalStack への接続。

本物の AWS が相手なら、リージョン文字列のタイプミスは解決できないホスト名を生みます — 到達できない Local のポートとまったく同じ EndpointConnectionError の形です。DynamoDB 固有の設定を調べる前に、そのプロファイルで aws sts get-caller-identity を実行して確認しましょう。

出典

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)

最終検証日 2026-07-13、上記にリンクした公式 AWS ドキュメントに照らして確認しました。

Could not connect to the endpoint URL (DynamoDB)

意味

発生する理由

修正方法

DynoTable を Local に向ける

関連するエラー

出典