Connection Troubleshooting

Configure Your Firewall

Verify that the ports your MongoDB deployment listens on are not blocked by a firewall on the same network. MongoDB uses port 27017 by default. To learn more about the default ports MongoDB uses and how to change them, see Default MongoDB Port.

Check Your Network Access List

Verify that your IP Address is listed in the IP Access List for your cluster. You can find your IP Access List in the Network Access section of the Atlas UI. To learn more about how to configure your IP Access List, see the Configure IP Access List Entries guide in the Atlas documentation.

Ensure MongoDB and Your Client Use the Same IP Address

In Node.js v17 and later, the DNS resolver uses IPv6 by default when both the client and host support both. For example, if MongoDB uses IPv4 and your client uses IPv6, the driver returns the previous error message.

You can configure your MongoDB deployment to use IPv6 mode when starting with mongod or mongos. For more information about how to specify IPv6 mode, see IP Binding in the server manual.

As an alternative, you can explicitly use IPv4 with your client by specifying family: 4 as an option to your MongoClient.

const client = new MongoClient(uri, {
  family: 4,
});

Control the Number of File Descriptors

A file descriptor is a unique identifier associated with an open process. In most operating systems, each open connection from the driver is associated with a file descriptor. Operating systems typically have a limit on the number of file descriptors used by a single process. An ECONNRESET error can occur if the number of connections exceeds this limit.

You can set the maximum number of connections by setting maxPoolSize. To resolve this error, you can decrease the number of maximum allowed connections by setting the value of maxPoolSize. Alternatively, you could increase the file descriptor limit in your operating system. To learn more about how to set maxPoolSize, see the API documentation for maxPoolSize .

Check Your Connection String

An invalid connection string is the most common cause of authentication issues when you attempt to connect to MongoDB by using SCRAM-SHA-256.

If your connection string contains a username and password, ensure that they are in the correct format. If the username or password includes any of the following characters, they must be percent encoded:

: / ? # [ ] @

The following example shows how to percent encode "#MyP@assword?":

console.log(encodeURIComponent('#MyP@assword?'));

This results in the following output:

"%23MyP%40assword%3F"

Verify the User Is in the Authentication Database

To successfully authenticate a connection by using a username and password with SCRAM-SHA-256, the username must be defined in the authentication database. The default authentication database is the admin database. To use a different database for authentication, specify the authSource in the connection string. The following example instructs the driver to use users as the authentication database:

const { MongoClient } = require("mongodb");
const uri = "mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=users";
const client = new MongoClient(uri);

Check the User Permissions

Verify that you've accessed the MongoDB deployment with the correct user. The term "message" in the error can be a command sent by the driver. If you are using a user that doesn't have permissions to send the command, the driver could generate this error.

Also ensure that the user has the appropriate permissions for the message you are sending. MongoDB uses Role-Based Access Control (RBAC) to control access to a MongoDB deployment. For more information about how to configure RBAC in MongoDB, see Default MongoDB Port.

Configure Your Firewall

The firewall needs to have an open port for communicating with the MongoDB instance. For more information about configuring the firewall, see Configure Your Firewall in the Connection Error section.

Check the Number of Connections

Each MongoClient instance supports a maximum number of concurrent open connections in its connection pool. You can configure the parameter maxPoolSize which defines this limit. The default value is 100. If there are already a number of open connections equal to maxPoolSize, the server waits until a connection becomes available. If this wait time exceeds the maxIdleTimeMS value, the driver responds with an error.

For more information about how connection pooling works, see the Connection Pool Overview in the Connection Pools page.

Set connectTimeoutMS

The driver may hang when it's unable to establish a connection because it takes too long attempting to reach unreachable replica set nodes. You can limit the time the driver spends attempting to establish the connection by using the connectTimeoutMS setting. To learn more about this setting, see the Timeout Options in the Server manual.

Ensure the connectTimeoutMS setting is not lower than the highest network latency you have for a member of the set. If one of the secondary members has a latency of 10000 milliseconds, setting the connectTimeoutMS to 9000 prevents the driver from ever connecting to that member.

The following example sets connectTimeoutMS to 10000 milliseconds.

const client = new MongoClient(uri, {
  connectTimeoutMS: 10000,
});