DOCSP-30724: Connection Troubleshooting page

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) <kotlin-faq>` for the {+driver-short+}
+   - The :ref:`Issues & Help <kotlin-issues-and-help>` topic for information about
+     reporting bugs, contributing to the driver, and additional resources
+   - The `MongoDB Community Forums <https://community.mongodb.com>`__ 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 <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 <https://tools.ietf.org/html/rfc3986#section-2.1>`__:
+
+   .. code-block:: none
+
+      : / ? # [ ] @
+
+
+If your MongoDB deployment is on MongoDB Atlas, you can check your connection
+string by using the :ref:`Atlas Connection Example <connect-atlas-kotlin-driver>`.
+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://<username>:<password>@<hostname>:<port>/?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 <kotlin-connection-string-port>`
+and :ref:`Authentication Error <kotlin-connection-string-auth>`.
+
+Verify User Is in Authentication Database
+-----------------------------------------
+
+The user needs to be recognized in your
+authentication database. This is described under :ref:`Authentication
+Error <kotlin-connection-admin>`.
+
+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-firewall>`.
+
+.. _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 <mcs-connectionpool-settings>`.
+
+Check the Number of Connections
+-------------------------------
+
+You might have too many open connections. The solution to this is described
+under :ref:`Error Sending Message <kotlin-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
+<https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html>`__
+for more information.

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 <kotlin-connection-troubleshooting>`
+for possible solutions.
+
 How Is the Kotlin Driver Different from Kmongo?
 -----------------------------------------------
 
@@ -41,7 +50,8 @@ key differences:
   or `GSON <https://github.com/google/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:
 

source/index.txt

@@ -13,6 +13,7 @@ MongoDB Kotlin Driver
    /fundamentals
    /api-documentation
    /faq
+   /connection-troubleshooting
    /issues-and-help
    /compatibility
    View the Source <https://github.com/mongodb/mongo-java-driver>
@@ -88,6 +89,13 @@ For answers to commonly asked questions about the MongoDB
 Kotlin Driver, see the :doc:`Frequently Asked Questions (FAQ) </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 </connection-troubleshooting>` section.
+
 Issues & Help
 -------------
 

source/issues-and-help.txt

@@ -1,3 +1,5 @@
+.. _kotlin-issues-and-help:
+
 =============
 Issues & Help
 =============