DynamoDB Local: Address already in use (port 8000)

TL;DR — DynamoDB Local はデフォルトでポート 8000 をバインドしますが、何かがすでにそれを保持しています。停止し忘れた以前の DynamoDB Local、別のサービス、あるいは重複した serverless-offline/コンテナです。ポート 8000 を解放するか、-port で別のポートで Local を起動して（クライアントをそこに向けて）ください。

意味

Exception in thread "main" java.net.BindException: Address already in use
   ... Failed to bind to port 8000

DynamoDB Local はポート 8000 でリッスンソケットを開く Java プロセスです。そのポートがすでにバインドされていると、JVM はそれを要求できず BindException で終了します。これは純粋に ローカルのポート競合 で、AWS や認証情報とは関係ありません。

発生する理由

• 以前の DynamoDB Local がまだ実行中 — 停止しなかった以前の java -jar DynamoDBLocal.jar（または docker run）。
• 別のサービスが 8000 を占有 — 同じポートの開発サーバー、プロキシ、無関係なアプリ。
• 重複したツール — serverless-dynamodb-local と serverless-offline が両方とも 8000 をバインドしようとする、または2つの docker-compose up スタック。
• クラッシュしたインスタンスがポートを短時間バインドしたまま（TIME_WAIT）、あるいはゾンビコンテナ。

サーバーレスとテストランナー

serverless-dynamodb-local プラグインや Jest の globalSetup フックは、暗黙のうちに Local を 起動しがちです — それに加えて docker run -p 8000:8000 amazon/dynamodb-local を手動でも 実行すると、Local 自体は正常に動いているのに、2 回目のバインドが BindException で落ちます。 1 つのマシンセッションにつき起動役は 1 つに絞りましょう。

macOS では、IDE のテストランナーが残した孤児の Java プロセスが定番の犯人です — lsof -i :8000 に、以前の Gradle 実行の PID を持つ java が出てくることがよくあります。

修正方法

1. ポートを占有しているものを見つけます:

   lsof -i :8000                       # macOS / Linux
   netstat -ano | findstr :8000        # Windows (note the PID)

   コピーコピーしました
2. そのプロセスを停止します（または古い DynamoDB Local）:

   kill <PID>                          # macOS / Linux
   taskkill /PID <PID> /F              # Windows

   コピーコピーしました
3. または別のポートで DynamoDB Local を実行し、クライアントを更新します:

   java -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -port 8001
   # then: endpoint = http://localhost:8001

   コピーコピーしました
4. Docker ですか？ マッピングのホスト側を変更し（-p 8001:8000）、8001 に接続します。
5. 重複したプラグイン/スタックを削除し、1つのプロセスだけがポートをバインドしようとするようにします。

DynoTable で

ポート 8000 を解放したら（あるいは Local を -port 8001 に移したら）、DynoTable を インストールし、Settings → Profiles → Add Profile で Local の プロファイルを追加します。エンドポイントに http://localhost:8000（または移した先のポート）、 プレースホルダーのリージョン、英数字のダミー認証情報を設定してください。テーブルを閲覧する前に、 Test Connection がエミュレータの待ち受けを確認してくれます。手順: DynamoDB Local を動かす · DynamoDB Local と LocalStack への接続。

ポートを変えたときは、プロファイルのエンドポイントも合わせて更新しましょう — Local が :8001 で待ち受けているのにプロファイルが :8000 を指したままだと、バインドの競合を 解消したあとでも接続拒否になります。 Local に到達できるようになったら、DynamoDB JSON コンバーターが シードデータの読み込みに役立ちます。

関連するエラー

• Unable to start DynamoDB Local process — エミュレータが他の理由（Java、ネイティブライブラリ）で起動に失敗する。
• Could not connect to DynamoDB Local (ECONNREFUSED) — 反対側: ダイヤルする先で何もリッスンしていない。
• Learn: Running DynamoDB Local

出典

• Deploying DynamoDB locally on your computer — AWS DynamoDB Developer Guide (default port 8000; "If port 8000 is unavailable, this command throws an exception")
• DynamoDB local usage notes — AWS DynamoDB Developer Guide (the -port command line option and full flag list)
• amazon/dynamodb-local — Docker Hub (official image and port mapping)

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