Node.jsにおける「listen EADDRINUSE: address already in use」エラーの解決方法

予期しないタイミングで発生する厄介なEADDRINUSEエラー。Node.jsサーバーを起動しようとしたところ、アプリケーションが動作する代わりに次のようなエラーが表示されます:Error: listen EADDRINUSE: address already in use :::3000。このNode.js EADDRINUSEエラーは、バインドしようとしているポートが既に別のプロセスによって使用されていることを意味します。このNode.jsにおけるポート競合を迅速に特定して修正する方法を説明します。

EADDRINUSEエラーの原因

listen EADDRINUSEエラーは、Node.jsアプリケーションが既に占有されているポートにバインドしようとしたときに発生します。よくある原因は以下の通りです:

• サーバーの前のインスタンスがまだ実行中
• 同じポートを使用している別のアプリケーション
• クラッシュしたNode.jsアプリのゾンビプロセス
• nodemonなどのホットリロードツールがクリーンアップに失敗
• IDEの統合ターミナルがプロセスを維持している

ポートを使用しているプロセスの特定方法

占有されているポートを解放する前に、何がそれを使用しているかを特定する必要があります。コマンドはオペレーティングシステムによって異なります。

macOSとLinux

lsofを使用してプロセスを見つけます:

lsof -i :3000

これはPID(プロセスID)を含むプロセスの詳細を返します:

COMMAND   PID    USER   FD   TYPE             DEVICE SIZE/OFF NODE NAME
node     12345   you   11u  IPv6 0xac745b2749fd2be3      0t0  TCP *:3000 (LISTEN)

Windows

netstatを使用してプロセスを特定します:

netstat -ano | findstr :3000

出力の最後の列にPIDが表示されます:

TCP    0.0.0.0:3000    0.0.0.0:0    LISTENING    12345

プロセスを終了してポートを解放する方法

PIDを取得したら、プロセスを終了してポートを解放できます。

macOSとLinuxでの解決方法

クイックワンライナー:

lsof -ti:3000 | xargs kill -9

手動アプローチ:

kill -15 12345  # グレースフルシャットダウン(推奨)
kill -9 12345   # -15が機能しない場合は強制終了

fuserを使用する代替方法:

sudo fuser -k 3000/tcp

Windowsでの解決方法

コマンドプロンプト:

taskkill /PID 12345 /F

PowerShell:

Stop-Process -Id 12345 -Force

GUI方式: タスクマネージャー(Ctrl+Shift+Esc)を開き、Node.jsプロセスを見つけて終了します。

将来のポート競合を防ぐ

グレースフルシャットダウンの実装

Node.jsサーバーに適切なクリーンアップハンドラーを追加してポートエラーを防ぎます:

const server = app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
});

// 終了シグナルを処理
process.on('SIGTERM', () => {
  server.close(() => {
    console.log('Server closed gracefully');
    process.exit(0);
  });
});

process.on('SIGINT', () => {
  server.close(() => {
    console.log('Server closed gracefully');
    process.exit(0);
  });
});

動的ポート選択の使用

ポートをハードコーディングしないでください。環境変数を使用するか、利用可能なポートを自動的に見つけます:

const PORT = process.env.PORT || 3000;

// またはバインド前にポートの可用性を確認
const net = require('net');

function getAvailablePort(startPort) {
  return new Promise((resolve) => {
    const server = net.createServer();
    server.listen(startPort, () => {
      const port = server.address().port;
      server.close(() => resolve(port));
    });
    server.on('error', () => {
      getAvailablePort(startPort + 1).then(resolve);
    });
  });
}

プログラムでエラーを処理

エラーをキャッチして適切に対応します:

server.on('error', (err) => {
  if (err.code === 'EADDRINUSE') {
    console.error(`Port ${PORT} is already in use`);
    // 別のポートを試すか、グレースフルに終了
    process.exit(1);
  }
});

よくあるシナリオとクイックフィックス

nodemonがポートを解放しない

nodemonを使用している場合は、Ctrl+Zではなく、Ctrl+Cで停止していることを確認してください。Ctrl+Zはポートを解放せずにプロセスを一時停止します。

Dockerコンテナの競合

実行中のコンテナを確認します:

docker ps
docker stop <container_id>

VS Codeターミナルの問題

サーバーを再起動する前に、すべての統合ターミナルを閉じてください。VS Codeはバックグラウンドでプロセスを維持することがあります。

コード内の複数のサーバーインスタンス

コードベース内でapp.listen()を複数回呼び出していないことを確認してください。このよくある間違いは、アドレスが既に使用中エラーを即座に引き起こします。

まとめ

Node.js EADDRINUSEエラーは厄介ですが、簡単に修正できます。lsofまたはnetstatでポートを使用しているプロセスを見つけ、それを終了し、将来の発生を防ぐために適切なシャットダウンハンドラーを実装してください。覚えておいてください:シグナルハンドラーによるグレースフルシャットダウンと動的ポート選択により、このNode.jsサーバーポートエラーに繰り返し対処する必要がなくなります。

よくある質問

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.