diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt new file mode 100644 index 00000000..a6098d4a --- /dev/null +++ b/source/connection-troubleshooting.txt @@ -0,0 +1,235 @@ +.. _kotlin-connection-troubleshooting: + +========================== +Connection Troubleshooting +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +This page offers potential solutions to issues you might see when +connecting to a MongoDB instance or replica set while using the +{+driver-long+}. + +.. note:: + + This page lists only connection issues. If you are having any other issues + with MongoDB, consider the following resources: + + - The :ref:`Frequently Asked Questions (FAQ) ` for the {+driver-short+} + - The :ref:`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 + +Connection Error +~~~~~~~~~~~~~~~~ + +The following error message is a general message indicating that the driver +cannot connect to a server on the specified hostname or port: + +.. code-block:: none + :copyable: false + + Error: couldn't connect to server 127.0.0.1:27017 + +If you receive this error, try the following methods to resolve the issue. + +.. _kotlin-connection-string-port: + +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. + +.. _kotlin-connection-firewall: + +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. + +.. important:: + + Do not open ports in your firewall unless you are sure that is the port used + by your MongoDB instance. + +Authentication Error +~~~~~~~~~~~~~~~~~~~~ + +The {+driver-short+} 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: + +.. code-block:: none + :copyable: false + + 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. + +.. _kotlin-connection-string-auth: + +Check Connection String +----------------------- + +An invalid connection string is the most common cause of authentication +issues when attempting to connect to MongoDB. + +.. note:: + + For more information about using connection strings with the {+driver-short+}, + see :ref:`Connection URI ` in the Connection Guide. + +If your connection string contains a username and password, ensure that they +are in the correct format. + +.. note:: + + If the username or password includes any of the following characters, they + must be `percent encoded `__: + + .. code-block:: none + + : / ? # [ ] @ + + +If your MongoDB deployment is on MongoDB Atlas, you can check your connection +string by using the :ref:`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. + +.. _kotlin-connection-admin: + +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: + +.. code-block:: kotlin + :copyable: false + + val mongoClient = + MongoClient.create("mongodb://:@:/?authSource=users") + +.. _kotlin-error-sending-message: + +Error Sending Message +~~~~~~~~~~~~~~~~~~~~~ + +When you send a request through the driver and it is unable to send the command, +it often displays the following general error message: + +.. code-block:: none + :copyable: false + + com.mongodb.MongoSocketWriteException: Exception sending message + +If you receive this error, try the following methods to resolve the issue. + +Check Connection String +----------------------- + +Verify that the connection string in +your app is accurate. This is described under :ref:`Connection Error ` +and :ref:`Authentication Error `. + +Verify User Is in Authentication Database +----------------------------------------- + +The user needs to be recognized in your +authentication database. This is described under :ref:`Authentication +Error `. + +Configure Firewall +------------------ + +The firewall needs to have an open port for communicating with the MongoDB +instance. This is described under :ref:`Connection Error `. + +.. _kotlin-connection-number-connections: + +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. + +Timeout 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: + +.. code-block:: none + :copyable: false + + Timed out after 30000 ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. + +.. code-block:: none + :copyable: false + + 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. + +Set ``maxConnectionTimeoutMS`` +------------------------------ + +The ``maxConnectionTimeoutMS`` option indicates the amount of time the +{+driver-short+} 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 :ref:`Connection Pool Settings `. + +Check the Number of Connections +------------------------------- + +You might have too many open connections. The solution to this is described +under :ref:`Error Sending Message `. + +Additional Tips +~~~~~~~~~~~~~~~ + +While not related to a specific error message, this section includes +additional information that can be useful when attempting to troubleshoot +connection issues. + +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. \ No newline at end of file diff --git a/source/faq.txt b/source/faq.txt index 7ff44d89..8ff74535 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -1,3 +1,5 @@ +.. _kotlin-faq: + === FAQ === @@ -8,6 +10,13 @@ FAQ :depth: 2 :class: singlecol +What if I can't connect to a MongoDB instance? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +If you have trouble connecting to a MongoDB deployment, see +the :ref:`Connection Troubleshooting Guide ` +for possible solutions. + How Is the Kotlin Driver Different from Kmongo? ----------------------------------------------- @@ -41,7 +50,8 @@ key differences: or `GSON `__. - The official driver does not support MongoDB shell commands. - The official driver supports type-safe queries with the Builders API, - whereas KMongo uses infix functions and property references for type-safe queries. + whereas KMongo uses infix functions and property references for + type-safe queries. .. _kotlin-faq-connection-pool: diff --git a/source/index.txt b/source/index.txt index 6b513995..9ff9d615 100644 --- a/source/index.txt +++ b/source/index.txt @@ -13,6 +13,7 @@ MongoDB Kotlin Driver /fundamentals /api-documentation /faq + /connection-troubleshooting /issues-and-help /compatibility View the Source @@ -88,6 +89,13 @@ For answers to commonly asked questions about the MongoDB Kotlin Driver, see the :doc:`Frequently Asked Questions (FAQ) ` section. +Connection Troubleshooting +-------------------------- + +For solutions to some issues you might experience when connecting to a MongoDB +deployment while using the {+driver-long+}, see the +:doc:`Connection Troubleshooting ` section. + Issues & Help ------------- diff --git a/source/issues-and-help.txt b/source/issues-and-help.txt index 39440b5d..f2b26602 100644 --- a/source/issues-and-help.txt +++ b/source/issues-and-help.txt @@ -1,3 +1,5 @@ +.. _kotlin-issues-and-help: + ============= Issues & Help =============