MongoDB Atlas Connection Errors: What Each One Actually Means

Posted by Kyle Hankinson July 19, 2026

---

First connections to MongoDB Atlas fail for a short, fixed list of reasons: your IP is not on the project's access list, your DNS resolver cannot answer SRV lookups, your credentials are wrong (or aimed at the wrong user system), or a special character in the password broke the URI. The frustrating part is that the error messages map to those causes badly. One of them even names the wrong culprit. This article is a decode table, with every error reproduced against real servers using mongosh 2.9.2.

What the two connection string formats actually do

Atlas hands you an SRV-style string:

mongodb+srv://appuser:secret@cluster0.ab1cd.mongodb.net/mydb

The +srv modifier means two things. First, the driver does not connect to cluster0.ab1cd.mongodb.net at all. It asks DNS for an SRV record listing the real cluster members, plus a TXT record carrying options. You can watch this happen yourself:

$ dig SRV _mongodb._tcp.cluster0.ab1cd.mongodb.net +short
0 0 27017 cluster0-shard-00-00-ab1cd.mongodb.net.
0 0 27017 cluster0-shard-00-01-ab1cd.mongodb.net.
0 0 27017 cluster0-shard-00-02-ab1cd.mongodb.net.

$ dig TXT cluster0.ab1cd.mongodb.net +short
"authSource=admin&replicaSet=Cluster0-shard-0"

Second, +srv automatically sets tls=true. That matters because Atlas refuses non-TLS connections on every tier, including free M0 clusters. SRV strings need drivers and shells from the MongoDB 3.6 era or newer; anything older must use the long form.

The long form is just the SRV answer written out by hand, and it connects to the same cluster identically (verified against a live Atlas cluster):

mongodb://appuser:secret@cluster0-shard-00-00-ab1cd.mongodb.net:27017,cluster0-shard-00-01-ab1cd.mongodb.net:27017,cluster0-shard-00-02-ab1cd.mongodb.net:27017/mydb?tls=true&replicaSet=Cluster0-shard-0&authSource=admin

Keep that equivalence in your pocket. It is the escape hatch for half the failures below.

The decode table

Error you see	What it actually means	Fix
Error: querySrv ENOTFOUND _mongodb._tcp... or ESERVFAIL	Your DNS resolver cannot answer the SRV lookup, or the hostname is mistyped	Switch DNS to 8.8.8.8 or 1.1.1.1, or use the long-form mongodb:// string
MongoServerSelectionError: Server selection timed out after 30000 ms	Nothing answered on port 27017: IP not on the Atlas access list, or a firewall eats the port	Add your IP under Network Access; test the port directly
...It looks like this is a MongoDB Atlas cluster. Please ensure that your Network Access List allows connections from your IP.	Atlas closed the connection during the handshake. Usually the access list, but this hint also appears when TLS is off	Check Network Access first; if your IP is listed, check that TLS is enabled
MongoServerError: bad auth : authentication failed	Wrong password, wrong username, or the wrong kind of user entirely	Use a database user, not your Atlas login; keep authSource=admin
MongoParseError: Password contains unescaped characters / URI malformed	A special character in the password broke URI parsing	Percent-encode the password
Client network socket disconnected before secure TLS connection was established	You sent tls=true to a server that does not speak TLS (typically local, never Atlas)	Drop tls=true for plain local servers

Now the details, because several of these lie to you.

querySrv ENOTFOUND: DNS, not MongoDB

Error: querySrv ENOTFOUND _mongodb._tcp.cluster0.ab1cd.mongodb.net

The driver never reached Atlas. This failure happens entirely inside DNS: corporate resolvers, some VPNs, hotel networks, and certain Docker DNS configurations answer A-record queries fine but fail SRV queries. ESERVFAIL is the same story with a less cooperative resolver. Two fixes, in order of preference:

• Point your machine (or container) at a public resolver such as 8.8.8.8 and retry.
• Sidestep SRV entirely: run the two dig commands above from any network that can resolve them, then build the long-form string. No SRV lookup, no problem.

If dig returns NXDOMAIN from every resolver you try, the hostname itself is wrong. Copy the string fresh from the Atlas UI.

Server selection timed out: the access list, usually

MongoServerSelectionError: Server selection timed out after 30000 ms

DNS worked, but every TCP connection to port 27017 went unanswered until the driver gave up. Atlas only accepts connections from IPs on the project's IP access list, and silence is exactly what a blocked IP gets. Check the Network Access page in the Atlas UI, and remember the ways your egress IP changes underneath you: home connections rotate, joining or leaving a VPN swaps it, and code running in a cloud function has no stable IP at all (that last case needs 0.0.0.0/0 or network peering). Atlas supports temporary entries that expire within seven days, which is the right tool for "let me in from this coffee shop."

If your IP is definitely listed, suspect the network instead. Offices and hotels commonly block outbound 27017. Test the port without any MongoDB machinery:

nc -zv cluster0-shard-00-00-ab1cd.mongodb.net 27017

No route there means no driver setting will save you. This is where tunneling out over SSH through a machine with clean egress earns its keep; the mechanics are covered in our SSH tunnel walkthrough.

The misleading Atlas hint

Newer drivers try to help and sometimes point at the wrong thing. Connecting to a live Atlas cluster with TLS deliberately disabled produced this:

MongoServerSelectionError: connection <monitor> to 198.51.100.7:27017 closed. It looks like this is a MongoDB Atlas cluster. Please ensure that your Network Access List allows connections from your IP.

The access list was fine. TLS was the problem. The driver shows this hint whenever Atlas abruptly closes the connection, and both a blocked IP and a missing TLS handshake look identical from the client side. Older drivers phrased the same situation as "Could not connect to any servers in your MongoDB Atlas cluster," the wording most Stack Overflow threads quote. Either way, read it as "Atlas hung up on me": check the access list first, then confirm TLS is actually on (it always is with +srv; it is easy to lose when hand-building a long-form string).

bad auth: which user, and where

MongoServerError: bad auth : authentication failed

That is Atlas's exact wording; a local mongod says Authentication failed. instead. Three causes worth checking in order:

• Wrong password. Obvious, but Atlas never shows the password again after creation, so reset it if unsure.
• Wrong user system. Atlas has two: your Atlas account (the web login, often Google SSO) and database users created under Database Access. Connection strings only ever use the second kind.
• Wrong authSource. Atlas database users live in the admin database. The SRV TXT record sets authSource=admin for you; hand-built long-form strings must include it. Verified locally: the same correct password fails with Authentication failed. when authSource points at the wrong database.

MongoParseError: the password ate your URI

The connection string manual requires percent-encoding for $ : / ? # [ ] @ in usernames and passwords. Tested with mongosh 2.9.2, the actual behavior is a mixed bag: a lone @ or : in the password happened to parse (the shell split on the last @), but a / produced MongoParseError: Password contains unescaped characters and a % produced MongoParseError: URI malformed. Other drivers are stricter than mongosh, so encode everything anyway:

p@ss:w0rd   becomes   p%40ss%3Aw0rd

After encoding, the same credentials authenticated successfully. A worse variant of this bug parses "successfully" but splits the string in the wrong place, sending the wrong host or password and surfacing as one of the other errors above. Special characters in the password belong on your suspect list for every error in this article.

Connection editors that take host, credentials, and options as separate fields avoid the encoding problem entirely, since there is no URI for the password to break. SQLPro for MongoDB takes that approach on Mac and iOS: a scheme picker for mongodb:// versus mongodb+srv://, a TLS toggle with an allow-invalid-certificates option, an auth source field, and built-in SSH tunneling for the networks where 27017 is simply closed.

The reverse TLS error, for completeness

Local development inverts the Atlas TLS situation. Pointing mongosh at a plain Docker mongod with tls=true fails like this (verified on MongoDB 8.2):

MongoServerSelectionError: Client network socket disconnected before secure TLS connection was established

If you see this against localhost, you copied an Atlas-shaped string at a server that never had certificates. Drop the TLS option. And if a plain mongodb://localhost:27017 string works but your Atlas string does not, you have confirmed the client is fine and the problem lives in one of the rows above.

---