Troubleshoot Connection Issues¶
This page outlines common connection issues and possible resolutions.
To learn more about connecting to an Atlas cluster, see the Get Started with Atlas tutorial.
Cluster Connect button is disabled¶
Your cluster Connect button may be disabled if your cluster is in the provisioning state. Your cluster needs to provision when it is first deployed, or when it is scaled up or down. The provisoning process can take up to 10 minutes, after which the Connect button will become enabled.
Connecting IP address not in IP Access List¶
Before connecting to your Atlas cluster, check that you added your host's IP address to the IP access list for your cluster's project. Atlas allows client connections only from IP addresses and CIDR address ranges in the IP access list.
Authentication to the cluster failed¶
To connect to Atlas, you must authenticate with a MongoDB database user. To create a database user for your cluster, see Configure Database Users.
If you have created a user and are having trouble authenticating, try the following:
- Check that you are using the correct username and password for your database user, and that you are connecting to the correct cluster.
- Check that you are specifying the correct
authSourcedatabase in your connection string.
- If you have a special character in your password, see Special characters in connection string password.
Too many open connections to your cluster¶
Atlas sets the limit for concurrent incoming connections to a
cluster based on the cluster tier. If you try to connect
when you are at this limit, MongoDB displays an error stating
connection refused because too many open connections.
For a detailed comparision of cluster tiers and their maximum concurrent connections, see Connection Limits and Cluster Tier.
- Close any open connections to your cluster not currently in use.
- Scale your cluster to a higher tier to support more concurrent connections.
- Restart your application.
- To prevent this issue in the future, consider using the
maxPoolSizeconnection string option to limit the number of connections in the connection pool.
To learn how to fix this issue, see Connection Alerts.
Attempting to connect to a cluster from behind a firewall¶
Atlas clusters operate on port
27017. You must be able to reach
this port to connect to your clusters. Additionally, ensure that the
appropriate ports are open for the following:
- For sharded clusters, grant access to port 27016.
- For BI Connector, grant access to port 27015.
You can check your ability to reach a port using the third-party Outgoing port tester.
To check your ability to reach port 27017, visit http://portquiz.net:27017.
If you can't access these ports, check your system firewall settings and ensure that they are not blocking access to these ports.
If you are using a
mongodb+srv:// connection string and your driver or shell can't find the
DNS host of the Atlas cluster, the cluster might be paused or
deleted. Check that the cluster exists and then resume the cluster if necessary.
Atlas automatically pauses idle
M0 clusters after 60 days
with no connections.
MongoDB Compass Troubleshooting¶
If you use MongoDB Compass to connect to your cluster, refer to the Compass Connection Errors for additional resources.
Connection String Issues¶
Incorrect Connection String Format¶
The connection string format you use to connect to Atlas depends on several factors, including:
mongoshell version. To learn more, see Connect via
- Your driver version. To learn more, see Connect via Driver.
Verify your connection string in a test environment before putting it into production.
Special Characters in Connection String Password¶
If you have special characters in your password, you must encode those characters if using your password in a connection string URI.
The following characters must be converted using percent encoding if included in a username or password:
: / ? # [ ] @
You can also use an online tool to encode your connection string, such as https://www.urlencoder.org/.
If your password in plain-text is
p@ssw0rd'9'!, you would need
to encode your password as:
Do not encode special characters in your password if you are using
your password outside of a connection string URI (for example,
pasting it into the
mongo shell or MongoDB Compass).
Connection String Incompatible with Driver Version¶
If you see this error message, your driver is likely out of date. For instructions on updating your driver, refer to your specific Driver Documentation.
Internet Service Provider DNS Blocks Connection String¶
When you use the DNS seed list connection string format to connect to Atlas, you might see the following error:
DNSHostNotFound: Failed to look up service “<MongoDB service name>”
This error may occur when using the default DNS server that your ISP provides. That DNS server might not support SRV lookups that the DNS seed list connection string format uses.
To resolve the issue, you can try changing your DNS configuration to use a public DNS server.
You can configure your network settings to use Google Public DNS instead of your ISP's DNS servers.
After you update your network settings to use a public DNS server, connect to the cluster.
Connection String Error with DB Tools on Ubuntu 18.04¶
If running Ubuntu 18.04 and using the
DNS seed list connection string
mongodb+srv://) to connect to Atlas from one of
the MongoDB Database Tools
mongorestore, etc), you might see the following
lookup nta8e.mongodb.net on 220.127.116.11:27017: cannot unmarshal DNS message
If so, use one of the following connection options instead:
- use the
--urioption with a non-SRV connection string (
- use the
--hostoption to specify the host to connect.
Connection Refused using SRV Connection String¶
When using the
DNS seed list connection string
mongodb+srv://) with a driver or Compass, you may
receive in the following error:
Error: querySrv ECONNREFUSED _mongodb._tcp.<SRV Record>
To remedy this issue, use the Standard Connection String format with Compass or that driver. With Compass, don't set the SRV Record value, set the Hostname and Port values instead.