From 4583f30c5144a0744c48938c47d8db866681a6c2 Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:12:52 -0400 Subject: [PATCH 1/7] DOCSP-30724: Connection Troubleshooting page --- source/connection-troubleshooting.txt | 239 ++++++++++++++++++++++++++ 1 file changed, 239 insertions(+) create mode 100644 source/connection-troubleshooting.txt diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt new file mode 100644 index 00000000..7d6791f4 --- /dev/null +++ b/source/connection-troubleshooting.txt @@ -0,0 +1,239 @@ +.. _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:`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. + +.. _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 = MongoClients.create("mongodb://:@:/?authSource=users"); + +Error Sending Message +~~~~~~~~~~~~~~~~~~~~~ + +When you end 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 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 :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 `. + +Miscellaneous Errors +~~~~~~~~~~~~~~~~~~~~ + +This section shows connection errors that do not fall into a broader category. +Each section lists the error message and then the specific steps you should +take to resolve it. + +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 From 29095be6f914373da7e7fe2dd2a070e7f8cb6d15 Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:27:03 -0400 Subject: [PATCH 2/7] add index --- source/index.txt | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/source/index.txt b/source/index.txt index 6b513995..127ae6c0 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 +`Connection Troubleshooting ` section. + Issues & Help ------------- From c4a68b4eb7560ab17accd018277ef4feb9912678 Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:41:50 -0400 Subject: [PATCH 3/7] self review --- source/connection-troubleshooting.txt | 7 +++++-- source/faq.txt | 2 ++ source/issues-and-help.txt | 2 ++ 3 files changed, 9 insertions(+), 2 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 7d6791f4..1707484c 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -126,7 +126,10 @@ database: .. code-block:: kotlin :copyable: false - val mongoClient = MongoClients.create("mongodb://:@:/?authSource=users"); + val mongoClient = + MongoClients.create("mongodb://:@:/?authSource=users"); + +.. _kotlin-error-sending-message: Error Sending Message ~~~~~~~~~~~~~~~~~~~~~ @@ -213,7 +216,7 @@ Check the Number of Connections ------------------------------- You might have too many open connections. The solution to this is described -under :ref:`Error Sending Message `. +under :ref:`Error Sending Message `. Miscellaneous Errors ~~~~~~~~~~~~~~~~~~~~ diff --git a/source/faq.txt b/source/faq.txt index 7ff44d89..d946c300 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -1,3 +1,5 @@ +.. _kotlin-faq: + === FAQ === 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 ============= From d15c8cdfe90563c7034b375460d77fdc946fb2ca Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:49:58 -0400 Subject: [PATCH 4/7] quick fix --- source/index.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/index.txt b/source/index.txt index 127ae6c0..9ff9d615 100644 --- a/source/index.txt +++ b/source/index.txt @@ -94,7 +94,7 @@ Connection Troubleshooting For solutions to some issues you might experience when connecting to a MongoDB deployment while using the {+driver-long+}, see the -`Connection Troubleshooting ` section. +:doc:`Connection Troubleshooting ` section. Issues & Help ------------- From 9d72234cb821799c09f3f5bad47df19eeb1069b3 Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:55:45 -0400 Subject: [PATCH 5/7] anotha one --- source/connection-troubleshooting.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 1707484c..9a45aba3 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -199,10 +199,10 @@ issue. 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. +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`` ----------------------------------------------------------- From 8d26e2fc4518934588082111c8453d96afd9af9d Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 14:57:42 -0400 Subject: [PATCH 6/7] last one --- source/connection-troubleshooting.txt | 7 ------- 1 file changed, 7 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 9a45aba3..332b3583 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -218,13 +218,6 @@ Check the Number of Connections You might have too many open connections. The solution to this is described under :ref:`Error Sending Message `. -Miscellaneous Errors -~~~~~~~~~~~~~~~~~~~~ - -This section shows connection errors that do not fall into a broader category. -Each section lists the error message and then the specific steps you should -take to resolve it. - Additional Tips ~~~~~~~~~~~~~~~ From c11d21734ee1fa7e549d36a902b00c61e7e150b0 Mon Sep 17 00:00:00 2001 From: Nick LDP Date: Fri, 14 Jul 2023 16:00:05 -0400 Subject: [PATCH 7/7] post review --- source/connection-troubleshooting.txt | 8 ++++---- source/faq.txt | 10 +++++++++- 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index 332b3583..a6098d4a 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -103,8 +103,8 @@ are in the correct format. If your MongoDB deployment is on MongoDB Atlas, you can check your connection -string by using the :ref:`Connect to MongoDB Atlas ` -code example. Make sure to replace the connection string in the example. +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 @@ -127,14 +127,14 @@ database: :copyable: false val mongoClient = - MongoClients.create("mongodb://:@:/?authSource=users"); + MongoClient.create("mongodb://:@:/?authSource=users") .. _kotlin-error-sending-message: Error Sending Message ~~~~~~~~~~~~~~~~~~~~~ -When you end a request through the driver and it is unable to send the command, +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 diff --git a/source/faq.txt b/source/faq.txt index d946c300..8ff74535 100644 --- a/source/faq.txt +++ b/source/faq.txt @@ -10,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? ----------------------------------------------- @@ -43,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: