Connection Troubleshooting

Check Connection String

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

Configure Firewall

Assuming that your MongoDB deployment uses the default port, verify that your firewall has port 27017 open. If your deployment is using a different port, verify that port is open in your firewall.

Check Connection String

An invalid connection string is the most common cause of authentication issues when attempting to connect to MongoDB.

If your connection string contains a username and password, ensure that they are in the correct format.

: / ? # [ ] @

If your MongoDB deployment is on MongoDB Atlas, you can check your connection string by using the Connect to MongoDB Atlas code example. Make sure to replace the connection string in the example.

When connecting to a replica set, you should include all of the hosts in the replica set in your connection string. Separate each of the hosts in the connection string with a comma. This enables the driver to establish a connection if one of the hosts is unreachable.

Verify User Is in Authentication Database

To successfully authenticate a connection by using a username and password, 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:

MongoClient mongoClient = MongoClients.create("mongodb://<username>:<password>@<hostname>:<port>/?authSource=users");

Check Connection String

Verify that the connection string in your app is accurate. This is described under Connection Error and Authentication Error.

Verify User Is in Authentication Database

The user needs to be recognized in your authentication database. This is described under Authentication Error.

Configure Firewall

The firewall needs to have an open port for communicating with the MongoDB instance. This is described under Connection Error.

Check the Number of Connections

Each MongoClient instance supports a maximum number of concurrent open connections in its connection pool. The configuration parameter maxPoolSize defines this value and is set to 100 by default. 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.

Install Certificate

If you are using Java version 8 or earlier, you might need to manually add a certificate to your trust store. You can either upgrade to a later version of the JDK or see our Security FAQ for information about how to add the certificate.

Set maxConnectionTimeoutMS

The maxConnectionTimeoutMS option indicates the amount of time the Java driver waits for a connection before timing out. The default value is 10000. You can increase this value or set it to 0 if you want the driver to never timeout.

Set maxConnectionLifeTime and maxConnectionIdleTime

Consider setting maxConnectionLifeTime and maxConnectionIdleTime. These parameters configure how long a connection can be maintained with a MongoDB instance. For more information about these parameters, see Connection Pool Settings.

Check the Number of Connections

You might have too many open connections. The solution to this is described under Error Sending Message.

Install Certificate

If you are using an older version of Java, you might need to manually install some certificates as described under Error Sending Message.

Monitor Thread Exception

INFO: Exception in monitor thread while connecting to server ssc-cluster-01-shard-00-02.9cbnp.mongodb.net:27017

To resolve this error, you need to manually install certificates as described under Error Sending Message.

Certificate Request Exception

javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request

This is a known error that can occur when using the TLS 1.3 protocol with specific versions of the JDK. If you encounter this error when connecting to your MongoDB instance or cluster, update your JDK to one of the following patch versions or newer:

• JDK 11.0.7

• JDK 13.0.3

• JDK 14.0.2

Get Log Information for TLS/SSL

When using TLS/SSL, you can use the -Djavax.net.debug=all system property to view additional log statements. This can help when attempting to debug any connection issues. See the Oracle guide to debugging TLS/SSL connections for more information.