MongoServerSelectionError: connect ECONNREFUSED

What it means

Before every operation, a MongoDB driver picks a server that can run it: for a write, the primary. It keeps trying until serverSelectionTimeoutMS runs out (30,000 ms by default), then gives up with MongoServerSelectionError (in the Node.js driver; Python’s is ServerSelectionTimeoutError). This is a client-side error with no server code: your query never reached a server.

The rest of the message is the last problem the driver hit, and it’s the clue:

Common causes

1. mongod isn’t running, or listens on another port. A local server that isn’t started, a container that stopped, or a Docker port that isn’t published to your Mac.
2. A host name that only resolves elsewhere. A Docker Compose service name (mongo) or a Kubernetes service works inside that network, not from your laptop.
3. The network drops the connection. On Atlas, only addresses in the project’s IP access list can connect; cloud firewalls and security groups do the same. The result is a timeout, not a refusal.
4. A replica set that doesn’t match. replicaSet= names a set the server isn’t in (or the server is a standalone), or the members advertise host names your machine can’t resolve, which is common with replica sets in Docker.
5. DNS for mongodb+srv://. The driver looks up SRV and TXT records; a typo in the cluster name, or a DNS server that won’t answer SRV queries, stops it before any connection.
6. localhost resolving to IPv6. mongod listens on IPv6 only when started with --ipv6. If the message names only ::1:27017, the client tried IPv6 alone; use 127.0.0.1 in the URL. Recent Node.js versions try both and list both addresses, as in the test below.

How to fix it

Check that something is listening

nc -vz <host> 27017

Connection to localhost port 37017 [tcp/*] succeeded!
nc: connectx to localhost port 37018 (tcp) failed: Connection refused

Refused: start mongod, or fix the port. For Docker, docker ps shows the published ports (0.0.0.0:27017->27017/tcp); from your Mac, connect to localhost and the port on the left.

Use a name that resolves where the client runs

dscacheutil -q host -a name <host>     # macOS

It prints the addresses the name resolves to, or nothing. Nothing: fix the name, or use an address your machine can reach (a published port on localhost, the server’s public name).

Check allowlists and firewalls

A timeout usually means a firewall. On Atlas, add your current public IP address to the project’s IP access list; home and office addresses change over time. See connecting to MongoDB Atlas.

Make the replica set settings match

The replicaSet option must equal the set’s name, and every member’s host name in the set’s configuration must resolve from the client, because the driver connects to those names, not the one in your URL. On the server:

rs.conf().members.map(m => m.host)

For a one-member set in Docker, connect to that one server directly and skip discovery:

mongodb://localhost:27017/?directConnection=true

Otherwise reconfigure the members with host names both sides can resolve.

Look up the SRV record

dig +short SRV _mongodb._tcp.<cluster host>

No records: check the cluster host name. If your network’s DNS won’t answer SRV queries, try another DNS server, or use a standard mongodb:// connection string that lists each host by name.

Fail sooner while you debug

Add serverSelectionTimeoutMS=5000 to the URL so each attempt fails in 5 seconds instead of 30.

Reproduce it

MongoDB 8.0.32 in Docker; the Node.js driver 7.5.0 bundled in mongosh 2.12.0, called the way application code calls it (new MongoClient(uri), then connect()). Nothing listening on 27018:

MongoServerSelectionError: connect ECONNREFUSED 127.0.0.1:27018

That took 30.0 seconds; with serverSelectionTimeoutMS=3000, 3.0. (mongosh itself reports the same problem at once, as MongoNetworkError: connect ECONNREFUSED 127.0.0.1:27018.) The other forms, each with a short timeout:

MongoServerSelectionError: getaddrinfo ENOTFOUND db.example.invalid
MongoServerSelectionError: Socket 'connect' timed out after 3002ms (connectTimeoutMS: 3000)
MongoServerSelectionError: Server selection timed out after 3000 ms
Error: querySrv ENOTFOUND _mongodb._tcp.cluster0.example.invalid

The third was replicaSet=rs0 against the standalone test server; the error’s reason.type was ReplicaSetNoPrimary. The SRV failure came back in 0.1 seconds, before server selection began.

From a Node.js script on the Mac (Node.js 25, driver 6.18.0), localhost with nothing listening listed both addresses it tried:

MongoServerSelectionError: connect ECONNREFUSED ::1:37018, connect ECONNREFUSED 127.0.0.1:37018

A one-member replica set in a temporary container, with its member configured as seo-mongo-rs:27017 (the container’s host name) and its port published as 37420. From the Mac, mongodb://localhost:37420/:

MongoServerSelectionError: getaddrinfo ENOTFOUND seo-mongo-rs

The driver reached the server, read the member list and then tried seo-mongo-rs, which only resolves inside that container. Adding directConnection=true to the same URL connected at once. A second set whose member was configured as localhost:37421, with the same port published, worked from the Mac with or without replicaSet=rs0.

In Inlet

Paste the same mongodb:// or mongodb+srv:// URL your app uses and Inlet fills the connection form, so you can test the host, port and options outside your code. Once connected, collections show as tables and queries use mongosh syntax, so you can check it’s the server you expect before you change your app’s settings.