Troubleshoot Connection Issues¶

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.

Incorrect connection string format¶

The connection string format you use to connect to Atlas depends on several factors, including:

• Your mongo shell version. To learn more, see Connect via mongo Shell.
• Your driver version. To learn more, see Connect via Driver.

Verify your connection string in a test environment before putting it into production.

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.

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.

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. For example, to check your ability to reach port 27017, visit http://portquiz.net:27017.

If you cannot access these ports, check your system firewall settings and ensure that they are not blocking access to these ports.

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. For a complete list of special characters and their corresponding encodings, see the ASCII Codes Table. Use the corresponding Hex value for your characters.

You can also use an online tool to encode your connection string, such as https://www.urlencoder.org/.

p%40ssw0rd%279%27%21

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.

Connection string blocked by DNS from your Internet Service Provider¶

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 might occur because the settings that your ISP uses in the Dynamic Host Configuration Protocol (DHCP) may block the Atlas address. To resolve the issue, change your Domain Name System (DNS) configuration to use a public DNS server.

For example, 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.

Cluster availability¶

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.

MongoDB Compass Troubleshooting¶

If you are using MongoDB Compass to connect to your cluster, you can visit the Compass Connection Errors page for additional troubleshooting resources.