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 Atlas Connection Example. Make sure to replace the connection string in the example with yours.

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:

val mongoClient =
MongoClient.create("mongodb://<db_username>:<db_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.

Set maxConnectionTimeoutMS

The maxConnectionTimeoutMS option indicates the amount of time the Kotlin 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.

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.