Navigation

Troubleshoot Connection Issues

On this page

This page outlines common connection issues and possible resolutions. Detailed instructions for connecting to an Atlas cluster can be found in the Get Started with Atlas tutorial.

Note

If you are an enterprise customer looking for support, please file a ticket. For community support, visit Community Support Resouces.

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 whitelisted

Before connecting to your Atlas cluster, be sure your host’s IP address is whitelisted for your cluster’s project. Atlas allows client connections only from whitelisted IP addresses and CIDR address ranges.

Incorrect connection string format

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

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.

Possible Solutions

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 authSource database 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.

Possible Solutions

  • 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 maxPoolSize connection string option to limit the number of connections in the connection pool.

For more details on fixing 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. 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/.

Example

If your password in plain-text is p@ssw0rd'9'!, you would need to encode your password as:

p%40ssw0rd%279%27%21

Important

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.

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.

© MongoDB, Inc 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc.