できない.dev

Node.js「EADDRINUSE: address already in use」の原因と直し方

EADDRINUSE: address already in use は、ポートを占有するプロセスを終了するかポート番号を変えれば直る。
占有元は lsof / netstat で特定する。

公開: 更新:

症状できない · exit 1
PORT=3000 node server.js
listen error: EADDRINUSE listen EADDRINUSE: address already in use :::3000
解決後できた · exit 0
PORT=3001 node server.js
listening on 3001

2026-09-27 に node:20(Node.js 20.20.2 / npm 10.8.2) で実際に打って取った出力。検証環境の詳細

要約

Error: listen EADDRINUSE: address already in use :::3000 のエラーは、同じポートを既に別のプロセスが占有しているために発生する。
lsof -i :3000 でプロセスを特定して終了する、もしくはポート番号を変更すれば解決する。

実行例

node:20(Debian GNU/Linux 12 bookworm)環境で上記の手順を動かすと、PORT=3000 を二重に bind しようとした2つ目のプロセスが listen EADDRINUSE: address already in use :::3000 を出力し、終了コード 1 で終了した。
PORT=3001 に切り替えた3つ目のプロセスは、終了コード 0 で正常に起動した。

$ PORT=3000 node server.js
listening on 3000
$ PORT=3000 node server.js
listen error: EADDRINUSE listen EADDRINUSE: address already in use :::3000
$ echo $?
1
$ PORT=3001 node server.js
listening on 3001
$ echo $?
0

— 2026-09-27 時点の出力

検証環境Node.js 20.20.2 / npm 10.8.2 / Python 3.11.2 / 2026-09-27 検証(ほか 1 件)
検証日
実行環境
node:20 Debian GNU/Linux 12 (bookworm)
バージョン
  • Node.js 20.20.2
  • npm 10.8.2
  • Python 3.11.2
  • Git 2.39.5

この記事の「実行例」は、上記の環境で実際にコマンドを実行して得られた出力をそのまま掲載しています。 再現手順はリポジトリの検証スクリプトとして管理し、定期的に再実行して出力を更新しています。

解決策

1. 占有プロセスを探して終了する

macOS / Linux:

lsof -i :3000
# または
ss -ltnp | grep :3000
kill -9 <pid>

Windows (PowerShell / cmd):

netstat -ano | findstr :3000
taskkill /PID <pid> /F

Node.js のシステムエラー一覧(新しいタブで開く) に EADDRINUSE の記載がある。

2. ポート番号を変える

環境変数で切り替える形にしておくと、衝突時に楽になる。

const port = process.env.PORT ?? 0; // 0 を渡すと OS が空きポートを割り当てる
server.listen(port, () => {
  console.log("listening on", server.address().port);
});

0 を渡すと OS が任意の空きポートを選ぶので、CI などで使いやすい(net.Server.listen の公式ドキュメント(新しいタブで開く) を参照)。

3. Docker Desktop / WSL の再起動

ホストで別プロセスが見当たらないのに EADDRINUSE が出る場合、Docker / WSL のポートフォワードが残っていることが多い。
Docker Desktop を再起動するか、wsl --shutdown を実行する。

4. TIME_WAIT 状態の回避

短時間で再起動を繰り返すスクリプトでは、前回終了時に server.close() を確実に呼ぶか、ポート 0 を使い回す。
Linux なら net.ipv4.tcp_tw_reuse=1 で TIME_WAIT を再利用できる場合がある。

よくある原因

  1. 直前のプロセスが残っている。
    ターミナルで Ctrl+C を押したつもりが、Node プロセスが孤児化して残っている。
  2. 別のアプリが同じポートを使っている。
    例えば 3000 は React dev サーバ、5432 は PostgreSQL などで、他の開発ツールとぶつかる。
  3. コンテナ / WSL のポートフォワードが残っている。
    Docker Desktop の published ports が解放されておらず、ホスト側の同番ポートを掴み続けている。
  4. TIME_WAIT 状態が続いている。
    直前にサーバが落ちたあと、TCP が TIME_WAIT で数十秒〜数分占有を続ける。