Fix: MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

The Node.js driver (and tools built on it) reports this when its TCP connection to the server is refused:

MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27017

ECONNREFUSED comes from the operating system: the host answered, but no process was listening on that address and port. The driver retries until its server selection timeout runs out, then throws this error. A variant with ::1:27017 means the client tried the IPv6 loopback address. The causes below are ordered from most to least common.

1. mongod is not running

sudo systemctl status mongod
sudo systemctl start mongod
sudo systemctl enable mongod          # start on boot

If systemd reports Unit mongod.service not found, reload the unit files with sudo systemctl daemon-reload and try again. On macOS with Homebrew the service is managed with brew services; on Windows check the MongoDB service in Services.

2. mongod starts and immediately stops

If the status shows failed or the process keeps restarting, the reason is in the log, by default /var/log/mongodb/mongod.log on Linux packages:

sudo tail -n 50 /var/log/mongodb/mongod.log
sudo journalctl -u mongod -n 50 --no-pager

• Data directory errors such as Data directory ... not found or a read-only lock file: the storage.dbPath directory is missing or not writable by the service account. On Debian and Ubuntu packages the default is /var/lib/mongodb, owned by mongodb; on RHEL-family packages it is /var/lib/mongo, owned by mongod. Fix ownership with chown -R on that directory.
• Socket is already in use: another process (often a second mongod started by hand) holds the port. Find it with sudo ss -tulpn | grep 27017.
• Configuration errors: a YAML typo in /etc/mongod.conf, such as a tab instead of spaces, stops startup. The log names the line.

3. Wrong address or port

Check where the server really listens and compare it with your connection string:

sudo ss -ltnp | grep mongod
grep -A3 '^net:' /etc/mongod.conf

• If net.port is not 27017, put the right port in the URI.
• If the error shows ::1:27017, localhost resolved to IPv6 while mongod listens only on 127.0.0.1. Use mongodb://127.0.0.1:27017 in the client, or add ::1 to net.bindIp.
• If the client runs on another machine, the default bindIp: 127.0.0.1 accepts only local connections. Add the server’s private interface address to net.bindIp (comma separated), restart, and allow the port in the firewall only from the client hosts.

net:
  port: 27017
  bindIp: 127.0.0.1,10.0.0.15

Do not bind to 0.0.0.0 or a public address until authentication is enabled and a firewall limits who can connect.

4. Containers and VMs

• Inside a container, 127.0.0.1 is the container itself, not the host or another container. Use the service name from your Compose file, for example mongodb://mongo:27017.
• If MongoDB runs in Docker and the app runs on the host, publish the port, for example -p 127.0.0.1:27017:27017, and check it with docker ps.
• In WSL, a server started on the Windows side and one inside the Linux distribution are separate. Make sure the client talks to the one that is actually running.

Confirm the fix

mongosh "mongodb://127.0.0.1:27017" --eval 'db.runCommand({ ping: 1 })'

A reply containing ok: 1 means the server is reachable. Then run your application with exactly the same host and port. If mongosh works but the app does not, print the URI the app really uses; environment variables and config files often differ between the two.

Official documentation

• MongoDB Manual: Install MongoDB Community on Linux
• MongoDB Manual: Troubleshoot Ubuntu installation
• MongoDB Manual: Configuration file options