Troubleshoot Connection Issues

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.

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.

To learn how to fix this issue, see Fix Connection Issues.

Connecting to the Atlas UI

Atlas uses a CDN to serve content quickly. If your organization uses a firewall, add the following Atlas CDN host to the firewall's allow list to prevent issues accessing the Atlas UI: https://assets.mongodb-cdn.com/.

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.

• For BI Connector, grant access to port 27015.

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

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

Incorrect Connection String Format

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

• Your mongosh version. To learn more, see Connect via mongosh.

• Your driver version. To learn more, see Connect via Drivers.

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, the following error message appears:

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

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

p%40ssw0rd%279%27%21

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

1
package main
2
3
import (
4
	"context"
5
	"fmt"
6
	"net/url"
7
8
	"go.mongodb.org/mongo-driver/bson"
9
	"go.mongodb.org/mongo-driver/mongo"
10
	"go.mongodb.org/mongo-driver/mongo/options"
11
)
12
13
func main() {
14
	username := "<username>"
15
	password := "<password>"
16
	cluster := "<clusterName>"
17
	authSource  := "<authSource>"
18
	authMechanism := "<authMechanism>"
19
20
	uri := "mongodb+srv://" + url.QueryEscape(username) + ":" + 
21
		url.QueryEscape(password) + "@" + cluster + 
22
		"/?authSource=" + authSource +
23
		"&authMechanism=" + authMechanism
24
25
	client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
26
	if err != nil {
27
		panic(err)
28
	}
29
	defer client.Disconnect(context.TODO())
30
31
	collection := client.Database("<dbName>").Collection("<collName>")
32
33
	cursor, err := collection.Find(context.TODO(), bson.D{})
34
	if err != nil {
35
		panic(err)
36
	}
37
38
	var results []bson.D
39
	if err = cursor.All(context.TODO(), &results); err != nil {
40
		panic(err)
41
	}
42
	for _, result := range results {
43
		fmt.Println(result)
44
	}
45
}

1
import com.mongodb.client.MongoClient;
2
import com.mongodb.client.MongoClients;
3
import com.mongodb.client.MongoCollection;
4
import com.mongodb.client.MongoDatabase;
5
6
import org.bson.Document;
7
import java.net.URLEncoder;
8
9
public class Encoding {
10
11
    public static void main(String [] args){
12
13
        try{
14
            String username = URLEncoder.encode("<username>", "UTF-8");
15
            String password = URLEncoder.encode("<password>", "UTF-8");
16
            String cluster = "<clusterName>";
17
            String authSource = "<authSource>";
18
            String authMechanism = "<authMechanism>";
19
            
20
            String uri = "mongodb+srv://" + username + ":" + password + "@" + cluster + 
21
                         "/?authSource=" + authSource + "&authMechanism=" + authMechanism;
22
23
            MongoClient mongoClient = MongoClients.create(uri);
24
    
25
            MongoDatabase database = mongoClient.getDatabase("<dbName>");
26
            MongoCollection<Document> collection = database.getCollection("<collName>");
27
            
28
            collection.find().forEach(doc -> System.out.println(doc.toJson()));
29
30
        } catch(Exception e){
31
            System.err.println(e.getCause());
32
33
        }
34
    }
35
}

1
const { MongoClient } = require("mongodb");
2
3
const username = encodeURIComponent("<username>");
4
const password = encodeURIComponent("<password>");
5
const cluster = "<clusterName>";
6
const authSource = "<authSource>";
7
const authMechanism = "<authMechanism>";
8
9
let uri =
10
  `mongodb+srv://${username}:${password}@${cluster}/?authSource=${authSource}&authMechanism=${authMechanism}`;
11
12
const client = new MongoClient(uri);
13
14
async function run() {
15
  try {
16
    await client.connect();
17
18
    const database = client.db("<dbName>");
19
    const ratings = database.collection("<collName>");
20
21
    const cursor = ratings.find();
22
23
    await cursor.forEach(doc => console.dir(doc));
24
  } finally {
25
    await client.close();
26
  }
27
}
28
run().catch(console.dir);

1
import pymongo
2
from urllib.parse import quote_plus
3
4
username = quote_plus('<username>')
5
password = quote_plus('<password>')
6
cluster = '<clusterName>'
7
authSource = '<authSource>'
8
authMechanism = '<authMechanism>'
9
10
uri = 'mongodb+srv://' + username + ':' + password + '@' + cluster + '/?authSource=' + authSource + '&authMechanism=' + authMechanism
11
12
client = pymongo.MongoClient(uri)
13
14
result = client["<dbName"]["<collName>"].find()
15
16
# print results
17
for i in result:
18
    print(i)

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.

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 format (mongodb+srv://) to connect to Atlas from one of the MongoDB Database Tools (mongodump, mongorestore, etc), you might see the following error:

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 (mongodb://).

• use the --host option to specify the host to connect.

Connection Refused using SRV Connection String

When using the DNS seed list connection string format (mongodb+srv://) with a driver or Compass, you may receive in the following error:

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

To begin troubleshooting you will need both the DNS SRV name and the nodes' individual hostnames and port numbers from the seed list connection string for the cluster.

To find the DNS SRV name:

1. Follow the Steps 1-6 in Connect Your Application.

2. In Step 7 select the latest version of the driver you chose.

3. The DNS SRV name begins after the @ symbol following the password and ends with .mongodb.net. - For example, cluster0.dfget.mongodb.net.

To find the nodes' hostnames and port numbers:

1. Follow the Steps 1-6 in Connect Your Application.

2. In Step 7 select the latest version of the driver you chose.

3. In Step 7 select the oldest driver version under Non-Stable API

   • Each of the hostnames is in a comma-separated list beginning after the @ symbol following the password and ending with .mongodb.net.

4. Note the port numbers after each of the hostnames.

   • The cluster's connection string may have a variety of hostnames and ports, depending on its topology and the connection method.

   • For more information on how Private Endpoints work, see Configure Private Endpoints.

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:

  Linux/MacOS:

  dig SRV _mongodb._tcp.<DNS SRV name>

  Windows:

  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:

  ;; 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 run this command:

  Linux/MacOS:

  dig <Node Hostname>

  Windows:

  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:

  ;; 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 run this command:

  Linux/Mac OS:

  ping -c 10 <Node Hostname>

  Windows:

  ping /n 10 <Node Hostname>

• End-to-End network connection test:

  Linux/Mac/OS:

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

  Windows:

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