Docs Menu
Docs Home
/ / /
Kotlin Coroutine

Connection Troubleshooting

On this page

  • Connection Error
  • Check Connection String
  • Configure Firewall
  • Authentication Error
  • Check Connection String
  • Verify User Is in Authentication Database
  • Error Sending Message
  • Check Connection String
  • Verify User Is in Authentication Database
  • Configure Firewall
  • Check the Number of Connections
  • Timeout Error
  • Set maxConnectionTimeoutMS
  • Set maxConnectionLifeTime and maxConnectionIdleTime
  • Check the Number of Connections
  • Additional Tips
  • Get Log Information for TLS/SSL

This page offers potential solutions to issues you might see when connecting to a MongoDB instance or replica set while using the MongoDB Kotlin Driver.


This page lists only connection issues. If you are having any other issues with MongoDB, consider the following resources:

  • The Frequently Asked Questions (FAQ) for the Kotlin driver

  • The Issues & Help topic for information about reporting bugs, contributing to the driver, and additional resources

  • The MongoDB Community Forums for questions, discussions, or general technical support

The following error message is a general message indicating that the driver cannot connect to a server on the specified hostname or port:

Error: couldn't connect to server

If you receive this error, try the following methods to resolve the issue.

Verify that the hostname and port number in the connection string are both accurate. In the sample error message, the hostname is 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.

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.


Do not open ports in your firewall unless you are sure that is the port used by your MongoDB instance.

The Kotlin driver can fail to connect to a MongoDB instance if the authorization is not configured correctly. This often results in an error message similar to the following:

Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017.

If you receive this error, try the following methods to resolve the issue.

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


For more information about using connection strings with the Kotlin driver, see Connection URI in the Connection Guide.

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:

: / ? # [ ] @

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.

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 =

When you send a request through the driver and it is unable to send the command, it often displays the following general error message:

com.mongodb.MongoSocketWriteException: Exception sending message

If you receive this error, try the following methods to resolve the issue.

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

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

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

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.

Sometimes when you send messages through the driver to the server, the messages take a while to respond. When this happens, you might receive an error message similar to one of the following error messages:

Timed out after 30000 ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}.
No server chosen by ReadPreferenceServerSelector{readPreference=primary} from cluster description

If you receive one of these errors, try the following methods to resolve the issue.

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.

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.

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

While not related to a specific error message, this section includes additional information that can be useful when attempting to troubleshoot connection issues.

When using TLS/SSL, you can use the 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.