MongoServerError: connect ECONNREFUSED 127.0.0.1:27017 の修正方法

TL;DR

ポート27017でのECONNREFUSEDは、アプリがMongoDBへの接続を試みたが、サービスが起動していないことを意味します — そのポートでリッスンしているものが何もありません。9割のケースは、以下のコマンド一つで解決できます：

# Linux (systemd)
sudo systemctl start mongod

# macOS (Homebrew)
brew services start mongodb-community

# Windows
net start MongoDB

根本原因

ECONNREFUSEDはTCPレベルのエラーです。OSが接続を積極的に拒否した — ポートが閉じています。これはいくつかの理由で発生します：

mongodプロセスが起動していない
MongoDBが別のポートまたはバインドアドレスでリッスンしている
ファイアウォールがポート27017をブロックしている
データディレクトリのパーミッションが正しくないため、mongodが起動できない
MongoDBが起動時にクラッシュした（ログに原因が記録されます）

ステップ1 — mongodが起動しているか確認する

# Linux / macOS
ps aux | grep mongod

# またはサービスの状態を確認する
sudo systemctl status mongod

inactive (dead)というステータスはMongoDBが停止している — または一度も起動していないことを意味します。ステップ2へ進んでください。

ステップ2 — MongoDBを起動する

# Linux (systemd — Ubuntu、Debian、RHEL、CentOS)
sudo systemctl start mongod
sudo systemctl enable mongod   # ブート時に自動起動

# macOS (Homebrew)
brew services start mongodb-community

# macOS (Homebrewなしでインストールした場合の手動起動)
mongod --config /usr/local/etc/mongod.conf

# Windows (管理者としてコマンドプロンプトを実行)
net start MongoDB

ステップ3 — ポートがリッスン状態か確認する

起動が成功したと思い込まないでください。MongoDBが実際にポート27017で接続を受け付けているか確認します：

# Linux / macOS
ss -tlnp | grep 27017
# または
lsof -i :27017

# Windows
netstat -ano | findstr 27017

次のような出力が表示されれば成功です：

tcp  0  0  127.0.0.1:27017  0.0.0.0:*  LISTEN  1234/mongod

この行はMongoDBがリッスンしていることを確認します。アプリを再度試してみてください — ECONNREFUSEDエラーは解消されているはずです。

ステップ4 — mongodの起動に失敗する場合はログを確認する

systemctl start mongodがエラーを返さないにもかかわらず、サービスがすぐに終了することがあります。ログに何が問題だったかが正確に記録されています：

# Linux
sudo journalctl -u mongod -n 50 --no-pager

# またはログファイルを直接確認する
sudo tail -n 50 /var/log/mongodb/mongod.log

よくあるログエラーと修正方法

データディレクトリのパーミッション拒否

# ログ出力:
# exception in initAndListen: NonExistentPath: Data directory /var/lib/mongodb not found.

# 修正: ディレクトリを作成してオーナーシップを修正する
sudo mkdir -p /var/lib/mongodb
sudo chown -R mongodb:mongodb /var/lib/mongodb
sudo chmod 755 /var/lib/mongodb

ポートがすでに使用中

# ログ出力:
# Address already in use for socket: 0.0.0.0:27017

# ポートを使用しているプロセスを確認する
sudo lsof -i :27017

# 古いmongodプロセスであれば強制終了する
sudo kill -9 <PID>

以前のクラッシュによるロックファイル

# ログ出力:
# Unclean shutdown detected. Please visit...

# ロックファイルを削除する
sudo rm /var/lib/mongodb/mongod.lock
sudo mongod --repair --dbpath /var/lib/mongodb
sudo systemctl start mongod

ステップ5 — mongod.confのバインドIPを確認する

MongoDBは起動しているのにまだ接続が拒否される場合は、バインドアドレスが原因である可能性が高いです。デフォルトでは、MongoDBは127.0.0.1のみでリッスンします — 他のホストやコンテナからの接続は認証レイヤーに到達する前に拒否されます。

# 設定ファイルを開く
sudo nano /etc/mongod.conf

# このセクションを確認する:
net:
  port: 27017
  bindIp: 127.0.0.1   # ← ローカル接続のみ受け付ける

Dockerコンテナや別サーバーなど、他のホストからの接続を許可するには、bindIpを変更します：

net:
  port: 27017
  bindIp: 0.0.0.0   # 任意のIPからの接続を受け付ける（ファイアウォールルールと併用すること）

次に再起動します：

sudo systemctl restart mongod

セキュリティに関する注意： MongoDBがファイアウォールの背後にある場合のみ0.0.0.0にバインドしてください。認証とネットワーク制限なしにポート27017をインターネットに直接公開しないでください。

ステップ6 — ファイアウォールの確認

リモートのMongoDBホストに接続していますか？ファイアウォールがポート27017のパケットを静かにドロップしている可能性があります。ポートを明示的に開放してください：

# Ubuntu (ufw)
sudo ufw allow 27017/tcp
sudo ufw status

# RHEL/CentOS (firewalld)
sudo firewall-cmd --permanent --add-port=27017/tcp
sudo firewall-cmd --reload

ステップ7 — DockerとDocker Compose

Dockerはネットワーキングに複雑さをもたらします。コンテナ内では、127.0.0.1はホストマシンではなくコンテナ自身を指します。そのため、Node.jsアプリがDockerで動作し、MongoDBがホスト上（または別のコンテナ内）にある場合、接続文字列を変更する必要があります：

# 誤り — コンテナのループバックに解決され、ホストではない
MONGODB_URI=mongodb://127.0.0.1:27017/mydb

# 正解 — host.docker.internalを使用する（macOS / WindowsのDocker Desktop）
MONGODB_URI=mongodb://host.docker.internal:27017/mydb

# 正解 — MongoDBがdocker-compose.ymlのサービスの場合、サービス名を使用する
MONGODB_URI=mongodb://mongo:27017/mydb

docker-compose.ymlの例：

services:
  app:
    build: .
    environment:
      - MONGODB_URI=mongodb://mongo:27017/mydb
    depends_on:
      - mongo
  mongo:
    image: mongo:7
    ports:
      - "27017:27017"

動作確認

mongoshを使用して接続がエンドツーエンドで機能することを確認します：

mongosh mongodb://127.0.0.1:27017
# 期待される出力:
# Connecting to: mongodb://127.0.0.1:27017/
# MongoServerVersion: 7.x.x
# >

またはMongooseを使用した簡単なNode.jsスニペットでテストします：

const mongoose = require('mongoose');
mongoose.connect('mongodb://127.0.0.1:27017/test')
  .then(() => console.log('接続成功!'))
  .catch(err => console.error(err));

出力に接続成功!と表示されれば修正が成功しています。ECONNREFUSEDエラーは解消されています。