> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

<!--
Tab options on this page. Append to the .md URL to filter:
  ?tabs=<id,...>   select specific tabs (e.g. ?tabs=nodejs,shell)
  ?allTabs=true    include every tab
  (no param)       default: one tab per tabset

Available tabs:
  drivers: go, java-sync, nodejs, python
-->

# 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](https://www.mongodb.com/docs/search/self-managed/current/connection/connect-to-search.md#std-label-mongot-connect) tutorial.

**Note:**

If you are an enterprise customer looking for support, [file a ticket](https://www.mongodb.com/docs/atlas/support/#request-support). For community support, visit [MongoDB Community Resources.](https://www.mongodb.com/community/)

You can use the [intelligent assistant](https://www.mongodb.com/docs/atlas/atlas-ui/query-with-natural-language/data-explorer-ai-assistant.md#std-label-de-ai-assistant) to assist in debugging your connection errors.

## Cluster Connect button is disabled

Your cluster's Connect button may be disabled if your cluster is in the provisioning state. Your cluster needs to provision when it is first deployed. Clusters also must provision when you [scaled them up or down.](https://www.mongodb.com/docs/atlas/scale-cluster.md#std-label-modify-cluster)

The Connect button will become enabled after Atlas provisions the cluster.

For free clusters, provisioning takes less than 15 seconds.

For Flex and Dedicated clusters, provisioning might take up to 10 minutes.

## 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](https://www.mongodb.com/docs/atlas/security/ip-access-list.md#std-label-access-list) for your cluster's project. Atlas allows client connections only from IP addresses and CIDR (Classless Inter-Domain Routing) 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.](https://www.mongodb.com/docs/atlas/security-add-mongodb-users.md#std-label-mongodb-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.](https://www.mongodb.com/docs/atlas/troubleshoot-connection.md#std-label-special-pass-characters)

## Too many open connections to your cluster

Atlas sets limits for concurrent incoming connections to a cluster. For clusters, this is 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.](https://www.mongodb.com/docs/atlas/reference/atlas-limits.md#std-label-connection-limits)

### Possible solutions

- Close any open connections to your cluster not currently in use.

- [Scale your cluster](https://www.mongodb.com/docs/atlas/scale-cluster.md#std-label-modify-cluster) to a higher tier to support more concurrent connections.

- Restart your application.

- To prevent this issue in the future, consider using the [`maxPoolSize`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.maxPoolSize) connection string option to limit the number of connections in the connection pool.

To learn how to fix this issue, see [Fix Connection Issues.](https://www.mongodb.com/docs/atlas/reference/alert-resolutions/connection-alerts.md#std-label-connection-alerts)

## Degraded performance in sharded clusters during spikes in connection counts

Atlas can generate an optimized SRV (DNS Service Record) connection string for sharded clusters using the load balancers from your private endpoint service. When you use an optimized connection string, Atlas limits the number of connections per `mongos` between your application and your sharded cluster. The limited connections per `mongos` improve performance during spikes in connection counts.

To learn more about optimized connection strings for sharded clusters behind a private endpoint, see [How can I optimize connection performance for sharded clusters using private endpoints?.](https://www.mongodb.com/docs/atlas/reference/faq/connection-changes.md#std-label-optimized-connection-strings)

## Attempting to connect from behind a firewall

### Connecting to the Atlas UI

Atlas uses a CDN (Content Delivery Network) to serve content quickly. If your organization uses a firewall, add the following Atlas CDN (Content Delivery Network) hosts to the firewall's allow list to prevent issues accessing the Atlas UI:

- `https://assets.mongodb-cdn.com/`

- `https://downloads.mongodb.com/` (required for the Data Explorer feature)

### Connecting to a Cluster

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.

You can check your ability to reach a port using the third-party Outgoing port tester.

**Example:**

To check your ability to reach port 27017, visit [http://portquiz.net:27017.](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.

## Cluster Availability

If you are using a `mongodb+srv://` [connection string](https://www.mongodb.com/docs/manual/reference/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. If this is a paused cluster, you can [resume](https://www.mongodb.com/docs/atlas/pause-terminate-cluster.md#std-label-resume-cluster) the cluster if necessary.

**Note:**

Atlas automatically pauses idle Free clusters (formerly known as `M0`) after 30 days with no connections.

## MongoDB Compass Troubleshooting

If you use MongoDB Compass to connect to your cluster and experience issues, see:

- [Connection Refused using SRV Connection String](https://www.mongodb.com/docs/atlas/troubleshoot-connection.md#std-label-atlas-connection-refused-srv) in this section.

- [Compass Connection Errors](https://www.mongodb.com/docs/compass/current/troubleshooting/connection-errors/) in the MongoDB Compass documentation.

If you use a [self-managed X.509 certificate](https://www.mongodb.com/docs/atlas/security-self-managed-x509.md#std-label-self-managed-x509) or an [auto-generated X.509 certificate](https://www.mongodb.com/docs/manual/core/security-x.509/) managed by Atlas to authenticate to the MongoDB database, when you connect to MongoDB Compass, you must:

1. In MongoDB Compass, choose Fill in connection fields individually.

2. In the Authentication dropdown,  select `X.509`.

3. Select More Options.

4. In the SSL dropdown, select Server and Client Validation.

5. Add the same path to the downloaded Atlas-managed certificate, or the self-managed certificate (depending on which you use) to each of these fields: Certificate Authority, Client Certificate, and Client Private Key.

To learn more, see [Connect to MongoDB](https://www.mongodb.com/docs/compass/current/connect/) in the MongoDB Compass documentation.

## Connection String Issues

### Incorrect Connection String Format

The [connection string format](https://www.mongodb.com/docs/manual/reference/connection-string/) you use to connect to Atlas depends on several factors, including:

- Your [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) version. To learn more, see [Connect to a Cluster via mongosh.](https://www.mongodb.com/docs/atlas/mongo-shell-connection.md#std-label-connect-mongo-shell)

- Your driver version. To learn more, see [Connect to a Cluster via Client Libraries.](https://www.mongodb.com/docs/atlas/driver-connection.md#std-label-connect-via-driver)

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

### Special Characters in Connection String Password

If your password includes special characters, and you are using your password in a connection string URI, encode the special characters.

If you try to update a password with a special character that requires [percent encoding](https://tools.ietf.org/html/3986#section-2.1), the following error message appears:

```text
This password contains special characters which will be URL-encoded.
```

**Note:**

The following characters and the space character must be converted using [percent encoding](https://tools.ietf.org/html/3986#section-2.1) if included in a username or password:

```none
: / ? # [ ] @ ! $ & ' ( ) * , ; = %
```

For example, if your password in plain-text is `p@ssw0rd'9'!`, you need to encode your password as:

```none
p%40ssw0rd%279%27%21
```

***

➤ Use the **Select your language** drop-down menu to set the language of the encoding example in this section.

***

### Node.js

```javascript
const { MongoClient } = require("mongodb");

const username = encodeURIComponent("<username>");
const password = encodeURIComponent("<password>");
const cluster = "<clusterName>";
const authSource = "<authSource>";
const authMechanism = "<authMechanism>";

let uri =
  `mongodb+srv://${username}:${password}@${cluster}/?authSource=${authSource}&authMechanism=${authMechanism}`;

const client = new MongoClient(uri);

async function run() {
  try {
    await client.connect();

    const database = client.db("<dbName>");
    const ratings = database.collection("<collName>");

    const cursor = ratings.find();

    await cursor.forEach(doc => console.dir(doc));
  } finally {
    await client.close();
  }
}
run().catch(console.dir);

```

**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 [`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)).

### 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.](https://www.mongodb.com/docs/drivers/)

### Internet Service Provider DNS Blocks Connection String

When you use the [DNS seed list connection string format](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-dns-seedlist) to connect to Atlas, you might see the following error:

```none
DNSHostNotFound: Failed to look up service "<MongoDB service name>"
```

This error may occur when using the default DNS (Domain Name System) server that your ISP (Internet Service Provider) provides. That DNS (Domain Name System) server might not support SRV (DNS Service Record) lookups that the DNS (Domain Name System) seed list connection string format uses.

To resolve the issue, you can try changing your DNS (Domain Name System) configuration to use a [public DNS server.](https://en.wikipedia.org/wiki/Public_recursive_name_server)

**Example:**

You can configure your network settings to [use Google Public DNS](https://developers.google.com//speed/public-dns/docs/using) instead of your ISP (Internet Service Provider)'s DNS (Domain Name System) servers.

After you update your network settings to use a public DNS (Domain Name System) server, [connect to the cluster.](https://www.mongodb.com/docs/atlas/connect-to-database-deployment.md#std-label-connect-to-database-deployment)

### Connection String Error with DB Tools

You might see the following error when using the [DNS seed list connection string](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-dns-seedlist) format (`mongodb+srv://`) to connect to Atlas from one of the [MongoDB Database Tools](https://www.mongodb.com/docs/database-tools/) (`mongodump`, `mongorestore`, etc):

```none
lookup nta8e.mongodb.net on 123.45.67.8:27017: cannot unmarshal DNS message
```

If so, use one of the following connection options instead:

- Use the `--uri` option with a [non-SRV connection string](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-standard-connection-string-format) (`mongodb://`).

- Use the `--host` option to specify the host to connect to.

### Connection Refused using SRV Connection String

When using the [DNS seed list connection string](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-dns-seedlist) format (`mongodb+srv://`) with a driver or Compass, you may receive in the following error:

```none
Error: querySrv ECONNREFUSED _mongodb._tcp.<SRV Record>
```

To troubleshoot this error, complete the following steps.

1. Find the DNS SRV Name

   Follow Steps 1-6 in [Connect Your Application.](https://www.mongodb.com/docs/atlas/driver-connection.md#std-label-drivers-connect-your-application)

   Select your driver and version.

   Under Use this connection string in your
   application, the SRV (DNS Service Record) hostname appears in the `mongodb+srv://` connection string. It is the part of the hostname ending with `.mongodb.net`.

   For example, `cluster0.dfget.mongodb.net`.

2. Find the Nodes' Hostnames and Port Numbers

   In the same Connect modal:

   Under Use this connection string in your
   application, turn off the SRV Connection String toggle.

   The standard connection string (`mongodb://`) displays, listing each node's hostname and port number.

   The cluster's connection string may have a variety of hostnames and ports, depending on its topology and the connection method. To learn more about Private Endpoints, see [Configure Private Endpoints.](https://www.mongodb.com/docs/atlas/security-configure-private-endpoints.md#std-label-atlas-configure-private-endpoint)

3. Test Basic Network Connectivity

   Run the following commands in a terminal or command prompt on the application server experiencing the issue:

   **DNS SRV resolution test**

   For Linux or macOS, run the following command:

   ```sh
   dig SRV _mongodb._tcp.<DNS SRV name>
   ```

   For Windows, run the following command:

   ```sh
   nslookup -debug -q=SRV  _mongodb._tcp.<DNS SRV name>
   ```

   Under the **ANSWER SECTION** in the response, you should see one result for each of the nodes in the cluster. For example:

   ```sh
   ;; ANSWER SECTION:
   _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-00.dfget.mongodb.net.
   _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-01.dfget.mongodb.net.
   _mongodb._tcp.gcluster0.dfget.mongodb.net. 60 IN SRV 0 0 27017 cluster0-shard-00-02.dfget.mongodb.net.
   ```

   **DNS node hostname resolution tests**

   For each hostname in the cluster:

   For Linux or macOS, run the following command:

   ```sh
   dig <Node Hostname>
   ```

   For Windows, run the following command:

   ```sh
   nslookup -debug -q=A <Node Hostname>
   ```

   Under the **ANSWER SECTION** in the response, you should see the IP address that the DNS hostname resolved to. For example:

   ```sh
   ;; ANSWER SECTION: cluster0-shard-00-00.ag9in.mongodb.net. 60 IN A 10.10.10.10
   ```

   **Ping test**

   **Note:**

   ICMP requests may be blocked by the cloud provider across Private Endpoint connections.

   For each hostname in the cluster:

   For Linux or macOS, run the following command:

   ```sh
   ping -c 10 <Node Hostname>
   ```

   For Windows, run the following command:

   ```sh
   ping /n 10 <Node Hostname>
   ```

   Review the output to check for packet loss and round-trip time (RTT). High packet loss or latency may indicate network issues between your server and the cluster nodes.

   **End-to-End network connection test**

   For Linux or macOS, run the following command:

   ```sh
   nc -zv <Node Hostname> <Node Port Number>
   ```

   For Windows, run the following command:

   ```sh
   Test-NetConnection -Port <Node Port Number> -InformationLevel "Detailed" -ComputerName "<Node Hostname>"
   ```

4. Resolve the Issue

   After running the tests in the previous step, use the following guidance to resolve the connection error based on which test failed:

   - **DNS SRV resolution test fails:** Your DNS resolver doesn't support SRV (DNS Service Record) record lookups, or outbound DNS traffic is blocked. Try either of the following:

     - Switch to the [non-SRV connection string](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-standard-connection-string-format) format (`mongodb://`) instead of `mongodb+srv://`. To get the non-SRV connection string, open the Connect modal in Atlas, select your driver and version, and turn off the SRV Connection String toggle under Use this connection string in your application.

     - Configure your network to use a [public DNS server](https://en.wikipedia.org/wiki/Public_recursive_name_server) that supports SRV (DNS Service Record) lookups, such as [Google Public DNS.](https://developers.google.com//speed/public-dns/docs/using)

   - **DNS node hostname resolution test fails:** Your DNS resolver can't resolve the individual node hostnames. If you use [private endpoints](https://www.mongodb.com/docs/atlas/security-configure-private-endpoints.md#std-label-private-endpoint), verify that your private endpoint DNS configuration is correct.

   - **Ping test fails:** ICMP traffic may be blocked by a firewall or the cloud provider. This does not necessarily indicate a TCP connection issue. Proceed to the end-to-end network connection test to verify TCP connectivity on port `27017`.

   - **End-to-end network connection test fails:** A firewall or network policy is blocking access to port `27017` on the node hostnames. Verify the following:

     - Add your application server's IP address to your cluster's [IP access list.](https://www.mongodb.com/docs/atlas/security/ip-access-list.md#std-label-access-list)

     - Allow outbound TCP connections on port `27017` through your firewall.

   - **All tests pass but the error persists:** The issue may be in your driver version. Older driver versions might not correctly support the SRV (DNS Service Record) connection string format. Update your driver to the latest version. You can also switch to the [standard (non-SRV) connection string format](https://www.mongodb.com/docs/manual/reference/connection-string-formats.md#std-label-connections-standard-connection-string-format) (`mongodb://`) by turning off the SRV Connection String toggle under Use this connection string in your application in the Connect modal.