Could not connect to DynamoDB Local (ECONNREFUSED)

TL;DR — クライアントがダイヤルしている先で何もリッスンしていません。DynamoDB Local が実際に期待するポートで実行されていること、そしてクライアントの endpoint が本物の AWS ではなく http://localhost:8000 を指していることを確認してください。

意味

Error: connect ECONNREFUSED 127.0.0.1:8000

TCP 接続が拒否されました。そのホスト/ポートでエミュレータが起動していないか、クライアントが何もリッスンしていない場所を指しています。

発生する理由

• DynamoDB Local が実行されていない — 起動しなかった、クラッシュした、またはシャットダウンされた（起動プロセスエラーを参照）。
• 誤ったポート — Local は 8000 にあるが、クライアントは 8080 をダイヤルしている（またはコンテナが別のホストポートをマッピングしている）。
• endpoint が未設定 — それがないと SDK は localhost ではなく 本物の AWS と通信する（そしてそれは認証/リージョンエラーとして、あるいはホストを上書きしていれば拒否として現れる）。
• Docker ネットワーキング — 別のコンテナからは localhost はそのコンテナ自身であり、ホストではありません。サービス名 / ホストゲートウェイを使ってください。
• localhost vs 127.0.0.1 の解決の癖（IPv6 ::1）。

よくあるセットアップ

Windows では、WSL とホストのどちらが localhost:8000 を占有しているかで食い違うことが あります — WSL では curl が通るのにホストの Node が ECONNREFUSED になるなら、ホスト側の クライアントを明示的に 127.0.0.1 に向けるか、クライアントが動く側で Local を起動して ください。

Local のプロファイルに対する DynoTable の Test Connection は、設定したエンドポイントで 何かが応答しているかを確かめる一番手早い方法です — Local が落ちていれば、同じ拒否された ソケットで失敗します。

修正方法

1. リッスンしているか確認します:

   curl http://localhost:8000        # DynamoDB Local returns a small response
   lsof -i :8000                     # something should own the port

   コピーコピーしました
2. クライアントに エンドポイントを明示的に設定します:

   import {DynamoDBClient} from '@aws-sdk/client-dynamodb';
   const client = new DynamoDBClient({
     region: 'local',
     endpoint: 'http://localhost:8000',
     credentials: {accessKeyId: 'local', secretAccessKey: 'local'}
   });

   コピーコピーしました
3. エミュレータが実際にバインドした ポートを一致させます（そして Docker の -p host:container マッピング）。
4. コンテナ間ですか？ localhost ではなく、コンテナ/サービス名（例: http://dynamodb-local:8000）または host.docker.internal を使います（host.docker.internal は Docker Desktop では自動的に解決します。Linux の Docker Engine では --add-host host.docker.internal:host-gateway を追加してください）。

DynoTable ワークベンチ

DynoTable をインストールし、Settings → Profiles → Add Profile で エンドポイント http://localhost:8000 を設定します。curl http://localhost:8000 が通ったら、 ⌘P で Local のプロファイルに切り替えましょう。Local が動いているあいだ、認証情報の ドットは緑のままのはずです。接続エラーで赤に変わるなら、プロファイルのポートかエンドポイントが、 エミュレータが待ち受けている場所と一致していません。Local に到達できるようになったら、 DynamoDB JSON コンバーターでフィクスチャを読み込めます。

curl http://localhost:8000 が失敗するなら、エミュレータは動いていません — まず Docker か jar を 起動してください（DynamoDB Local のプロセスを起動できない）。 ポートは違うが何かが待ち受けている場合は、ECONNREFUSED ではなく一般的な HTTP エラーが出ることが あります。lsof -i :8000 が示す内容にプロファイルのエンドポイントを合わせましょう。 ガイド: DynamoDB Local と LocalStack への接続。

関連するエラー

• DynamoDB Local のプロセスを起動できない
• 設定にリージョンがない
• 学習: DynamoDB Local を動かす · DynamoDB Local / LocalStack への接続

出典

• Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000, launch command, Docker run/compose examples)
• DynamoDB local usage notes — AWS DynamoDB Developer Guide (local endpoint http://localhost:8000; SDKs require an access key + region value)
• amazon/dynamodb-local — Docker Hub (official image, docker run -p 8000:8000 amazon/dynamodb-local)
• docker run --add-host — Docker CLI reference (host.docker.internal / host-gateway for container-to-host connections)

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