Connection Troubleshooting

Check Your Connection String

Verify that the hostname and port number in the connection string are both accurate. The default port value for a MongoDB instance is 27017, but you can configure MongoDB to communicate on another port.

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 Connection String

An invalid connection string is the most common cause of authentication issues when attempting to connect to MongoDB using connection strings and SCRAM-SHA-256 or SCRAM-SHA-1.

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 "#MyPassword?":

Console.WriteLine(System.Web.HttpUtility.UrlEncode("#MyPassword?"));

This results in the following output:

%23MyPassword%3F

Verify the MongoClientSettings Properties

You can use a MongoClientSettings object to configure the settings when attempting to connect to a MongoDB deployment. You can use the Credential property to set authentication information. If the credential information is not correct, you will receive authentication errors when you attempt to connect to your MongoDB deployment.

Verify the User Is in the Authentication Database

To successfully authenticate a connection by using a username and password with SCRAM-SHA-256 or SCRAM-SHA-1, 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 option in the connection string. The following example instructs the driver to use users as the authentication database:

using MongoDB.Driver;
// Connection URI
const string connectionUri = "mongodb://<username>:<password>@<hostname>:<port>/?authSource=users";
// Create a new client and connect to the server
var client = new MongoClient(connectionUri);

You can also set configuration settings by creating a MongoClientSettings object and passing that to the MongoClient constructor. You can use the Credential property to set the login credentials including specifying the authentication database. For more information about using MongoClientSettings as well as some examples, see Using MongoClientSettings.

You can check if this is the issue by attempting to connect to a MongoDB instance hosted on the local machine with the same code. A deployment on the same machine doesn't require any authorization to connect.

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 MaxConnectionPoolSize which defines this limit. The default value is 100. If there are already a number of open connections equal to MaxConnectionPoolSize, the server waits until a connection becomes available. If this wait time exceeds the MaxConnectionIdleTime value, the driver responds with an error.

For more information about how connection pooling works, see How Does Connection Pooling Work in the .NET/C# Driver? in the FAQ.

Check the Number of Connections

If you need to create more open connections, increase MaxConnectionPoolSize. For more information about checking the number of connections, see Check the Number of Connections in the Error Sending Message section.

Set connectTimeoutMS

The driver may hang when it's unable to establish a connection because the driver 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 connectTimeMS setting. To learn more about this setting, see the Timeout Options in the Server manual.

You should ensure the connectTimeoutMS setting is not lower than the highest network latency you have to 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.

You can set this option on the connection string. The following example sets connectTimeoutMS to 10000 milliseconds.

using MongoDB.Driver;
// Connection URI
const string connectionUri = "mongodb://<username>:<password>@<hostname>:<port>/?connectTimeoutMS=10000";
// Create a new client and connect to the server
var client = new MongoClient(connectionUri);

You can also set configuration settings by creating a MongoClientSettings object and passing that to the MongoClient constructor. For more information about using MongoClientSettings as well as some examples, see Using MongoClientSettings.

Check the Number of Connections

The number of connections to the server may exceed MaxConnectionPoolSize. For more information about checking the number of connections, see Check the Number of Connections in the Error Sending Message section.