About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.
A MongoDB client error that ends in connect ECONNREFUSED 127.0.0.1:27017 means the client tried to open a TCP connection to port 27017 on the local loopback address and the operating system refused it. The Linux connect(2) manual defines ECONNREFUSED as: "A connect() on a stream socket found no one listening on the remote address." So either mongod is not running, it listens on a different address or port, or the client runs on a different machine from mongod. Check the service first, then the listener.
What the error means
The error comes from the client's operating system, not from MongoDB. No MongoDB message is exchanged, because the connection never began. The class name in front of the message depends on the driver and its version. The only form the MongoDB Node.js driver page prints is MongoServerSelectionError: connect ECONNREFUSED <IPv6 address>:<port>. The part that matters is connect ECONNREFUSED and the address and port that follow.
The defaults matter. The manual gives the default port for mongod as 27017, 27018 if mongod is a shard member, and 27019 for a config server member. For net.bindIp it gives the default localhost, and it says mongod from official Debian and Red Hat packages has bind_ip set to 127.0.0.1. The install tutorials say that with this default the instance "only accepts connections from clients running on the same machine".
So a refusal on 127.0.0.1:27017 has a short list of causes. Nothing is running. Something runs on another port. net.bindIp has been set to other addresses and no longer includes 127.0.0.1. Or the client is not on the machine where mongod runs. When the message shows an IPv6 address, the driver page explains a different case: with Node.js v17 and later the resolver uses IPv6 by default when both sides support it, while mongod listens on IPv4. A message that names 127.0.0.1 is already IPv4, so that case does not apply to it.
Likely causes
| Cause | What you see | How to confirm |
|---|---|---|
mongod is not running (stopped, crashed, failed to start) |
Every client on the host fails | systemctl status mongod shows it is not active |
mongod listens on another port |
ss shows a different port for mongod |
ss -ltnp and net.port in the configuration file |
net.bindIp lacks 127.0.0.1 |
ss shows the listener on one address only |
net.bindIp in the file, and the listener address in ss |
| Start-up options override the file | The command line in systemctl status has --bind_ip or --port |
The manual says --bind_ip overrides the file setting |
| Client is on another machine | Works from the database host, refused elsewhere | mongosh succeeds on the database host with the same address |
Prove the cause before changing anything
All of these are read-only. Run ss from an administrator account, for example with sudo; the ss manual says only that -p shows processes using sockets.
1. Is the service running?
systemctl status mongod
The manual's install page shows Active: active (running) and the process line /usr/bin/mongod --config /etc/mongod.conf for a running service. Anything else, such as inactive (dead) or failed, means the first fix applies. Note any --bind_ip or --port in the process line, because the manual says the --bind_ip option overrides net.bindIp in the file.
2. What is listening?
ss -ltnp
The ss manual describes -l as showing only listening sockets, -t as TCP, -n as not resolving service names and -p as showing the processes using sockets. Look for a line with mongod. A good result has 127.0.0.1:27017 in the local address column. If you see 192.0.2.10:27017 only, or a different port, that is the cause. No mongod line means it is not running or has not yet created its listening socket.
3. What does the configuration file say?
Read /etc/mongod.conf (the file named in the process line) and note net.port, net.bindIp, systemLog.path and storage.dbPath.
4. Try the address from the database host.
mongosh --host 127.0.0.1 --port 27017
The shell manual documents --host and --port, and says mongosh without options connects to localhost on port 27017. If this connects on the database host but your application fails, the client is elsewhere or uses a different address.
5. Read the last lines of the log.
The manual's example configuration file uses /var/log/mongodb/mongod.log as systemLog.path. Use the path in your file:
tail -n 50 /var/log/mongodb/mongod.log
If mongod failed to start, the reason is in this log. Reading a failed unit is covered under the title "systemd: "Job for nginx.service failed because the control process exited with error code" - find the real error".
Fix
mongod is not running
The install tutorial's start command is sudo systemctl start mongod.
First save the current state and the end of the log:
systemctl status mongod > ~/mongod-status-2026-11-22.txt
sudo tail -n 50 /var/log/mongodb/mongod.log > ~/mongod-log-tail-2026-11-22.txt
Disruptive step: the next command starts the database. Clients that keep retrying will connect and write at once, and if mongod stopped because of a fault, starting it again may fail the same way. Check the saved log tail before you run it.
Start the service and check it:
sudo systemctl start mongod
systemctl status mongod
To undo it: if the saved status showed the service was not running before, stop it again with sudo systemctl stop mongod. The systemctl manual says stop deactivates the unit, so connected clients are disconnected. If it was running before, there is nothing to undo.
The client uses the wrong address or port
The least risky fix changes the client and leaves the database alone. A shard member listens on 27018 and a config server member on 27019 by default, so a client that expects 27017 may simply have the wrong port.
First note the application's current connection string or its host and port settings, character for character. Copy the current line into a text file or your change record before you edit anything.
Risk: the next change points a live application at a different database address, so its writes go wherever the new address leads. Confirm with ss that the address and port belong to the right mongod first.
Edit the connection string to use the address and port that ss showed, then restart the application as its documentation describes.
To undo it: put the noted connection string back and restart the application. No server change is involved.
net.bindIp lacks 127.0.0.1
The manual describes net.bindIp as a comma-separated list, for example localhost,/tmp/mongod.sock. It also warns: "Before you bind your instance to a publicly-accessible IP address, you must secure your cluster from unauthorized access." The Linux package init scripts "depend on specific values for systemLog.path, storage.dbPath, and processManagement.fork", so change only net.bindIp.
First save the configuration file. Use the file named in the systemctl status process line; the commands below assume /etc/mongod.conf. Check that it exists:
ls -l /etc/mongod.conf
If it does not exist, stop: this step edits an existing configuration file, and a server started with another file or only with command-line options needs that file or those options changed instead. If it exists, save it:
sudo cp -p /etc/mongod.conf /etc/mongod.conf.2026-11-22
Disruptive step: the next change takes effect when mongod restarts, which disconnects every client, and a listener on a non-loopback address makes the database reachable from that network. Confirm that a firewall and authentication are in place first.
Edit net.bindIp in /etc/mongod.conf so it lists 127.0.0.1 and the private address you need, for example bindIp: 127.0.0.1,192.0.2.10. Then restart and check:
sudo systemctl restart mongod
ss -ltnp
The systemctl manual says restart stops and then starts the unit. A good result shows mongod on both addresses.
To undo it: first prove the saved copy exists with ls -l /etc/mongod.conf.2026-11-22. Only then put it back under its original name, restart, and check.
sudo cp -p /etc/mongod.conf.2026-11-22 /etc/mongod.conf
sudo systemctl restart mongod
ss -ltnp
Example (illustrative): On db01, the application and mongod run together. The application logs connect ECONNREFUSED 127.0.0.1:27017. systemctl status mongod shows active (running). ss -ltnp shows mongod listening on 192.0.2.10:27017 and nothing on 127.0.0.1. /etc/mongod.conf has bindIp: 192.0.2.10. The administrator saves the file, changes the line to bindIp: 127.0.0.1,192.0.2.10, restarts during a quiet window, and the application connects.
Confirm the fix
systemctl status mongodshowsactive (running).ss -ltnpshowsmongodon the address and port the client uses.mongosh --host 127.0.0.1 --port 27017connects, and the application connects.- The last lines of the log show no new startup errors.
What to watch afterwards
- The install tutorial's boot setting is
sudo systemctl enable mongod. Ifmongodis missing after every reboot, checksystemctl is-enabled mongod. - Alert on the service state, not only on application errors.
- Keep the connection string in one place per application so a changed port or address needs one edit.
- Recheck
net.bindIpwhenever a network address changes. The manual says "To avoid configuration updates due to IP address changes, use DNS hostnames instead of IP addresses."
Read next
Related articles you may want next.
- Backup & RecoveryMongoDB backups: what mongodump can and cannot do, filesystem snapshots, and restoring a replica setHow MongoDB backups really work: mongodump and --oplog limits, filesystem snapshot requirements, restore version rules and restoring a replica set correctly.Read article
- TroubleshootingPostgreSQL "Connection refused" on port 5432: listen_addresses, the service and the firewallPostgreSQL 'Connection refused' on port 5432? Check the service, listen_addresses (default localhost) and the port, then the network path.Read article
- Troubleshootingsystemd: "Job for nginx.service failed because the control process exited with error code" - find the real errorJob for nginx.service failed because the control process exited? Read systemctl status and journalctl, decode the exit status, test the config.Read article
Risks and limits
- These commands have not been run or lab-tested.
- Binding to a non-loopback address exposes the port. The manual says that before binding to a publicly-accessible address you must secure the cluster, and its IP binding page says to bind to a private or internal interface if there is more than one.
- Replica sets, Atlas and Windows services are not covered. The Node.js driver page covers the Atlas IP access list separately.
- Package versions differ. The tutorials show output from MongoDB 9.0, and paths on your system may differ.
Sources
- connect(2) — Linux man-pages 6.19, 2026-02-08, accessed 22 November 2026
- ss(8) — iproute2 manual page as hosted on man7.org, colophon 2026-08-04, accessed 22 November 2026
- systemctl — systemd 262 documentation, no date shown, accessed 22 November 2026
- MongoDB Manual: Self-Managed Configuration File Options — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Manual: IP Binding in Self-Managed Deployments — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Manual: Default MongoDB Port — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Manual: Install MongoDB Community on Linux — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Manual: mongod — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Shell: Connect to a Deployment — MongoDB, no date shown, accessed 22 November 2026
- MongoDB Node.js Driver: Connection Troubleshooting — MongoDB, no date shown, accessed 22 November 2026
This article was originally published on .