From 067cbd20e794b317ec9f47147deb0ca28c854ee5 Mon Sep 17 00:00:00 2001 From: Angela Date: Tue, 8 Jul 2025 12:02:15 -0400 Subject: [PATCH 1/8] connection troubleshooting: --- source/connect.txt | 3 +- source/connect/connection-options.txt | 1 + source/connect/connection-pools | 14 + source/connect/connection-targets.txt | 2 + source/connect/connection-troubleshooting.txt | 307 ++++++++++++++++++ 5 files changed, 325 insertions(+), 2 deletions(-) create mode 100644 source/connect/connection-pools create mode 100644 source/connect/connection-troubleshooting.txt diff --git a/source/connect.txt b/source/connect.txt index cc47d76d..0b5900f2 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -26,8 +26,7 @@ Connection Guide Choose a Connection Target Connection Options AWS Lambda - -.. /connect/connection-troubleshooting + Connection Troubleshooting Overview -------- diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 2c065e10..6144d81e 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -23,6 +23,7 @@ Specify Connection Options Stable API Limit Server Execution Time + Connection Pools .. /connect/network-compression .. /connect/server-selection diff --git a/source/connect/connection-pools b/source/connect/connection-pools new file mode 100644 index 00000000..e83fa767 --- /dev/null +++ b/source/connect/connection-pools @@ -0,0 +1,14 @@ +.. _kotlin-sync-connection-pools: + +================ +Connection Pools +================ + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + + +.. _kotlin-sync-connection-pool-settings: \ No newline at end of file diff --git a/source/connect/connection-targets.txt b/source/connect/connection-targets.txt index f0332efd..3696be0d 100644 --- a/source/connect/connection-targets.txt +++ b/source/connect/connection-targets.txt @@ -70,6 +70,8 @@ deployment: :end-before: end-connect-local :dedent: +.. _kotlin-sync-connect-replica-set: + Replica Sets ------------ diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt new file mode 100644 index 00000000..ea5da166 --- /dev/null +++ b/source/connect/connection-troubleshooting.txt @@ -0,0 +1,307 @@ +.. _kotlin-sync-connection-troubleshooting: + +========================== +Connection Troubleshooting +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, disconnected, deployment + +.. sharedinclude:: dbx/connection-troubleshooting.rst + + .. replacement:: non-connection-issue-callout + + .. note:: + + This page addresses only connection issues. If you encounter other + issues when using MongoDB or the driver, visit the following resources: + + - The :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the driver, and + finding more resources + - The `:community-forum:`MongoDB Community Forums ` for + questions, discussions, or general technical support + + .. replacement:: server-selection-timeout-error + + .. code-block:: none + :copyable: false + + Error: couldn't connect to server 127.0.0.1:27017 + + .. replacement:: check-connection-string-anchor + + .. _kotlin-sync-connection-string-port: + + .. replacement:: multiple-hosts-connection-guide-link + + To learn how to specify multiple replica set hosts, see + :ref:`kotlin-sync-connect-replica-set` section of the Connection Guide. + + .. replacement:: configure-firewall-anchor + + .. _kotlin-sync-connection-firewall: + + .. replacement:: authentication-error-anchor + + .. _kotlin-sync-authentication-error: + + .. replacement:: scram-failure-error + + .. code-block:: none + :copyable: false + + Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + + .. replacement:: check-credentials-formatting-anchor + + .. _kotlin-sync-connection-string-auth: + + .. replacement:: learn-more-connection-string-admonition + + .. tip:: + + For more information about using connection strings, + see :ref:`Connection URI ` in the Connection Guide. + + .. replacement:: percent-encode-example + + .. replacement:: verify-authentication-database-anchor + + .. _kotlin-sync-verify-auth-db: + + .. replacement:: credentials-provider-alternative-method-description + + If you construct a client by using a ``MongoCredential``, the builder method + corresponds to the authentication mechanism. The following code shows the builder + method for the ``SCRAM-SHA-256`` authentication mechanism: + + .. code-block:: kotlin + :copyable: false + + val credential = MongoCredential.createScramSha256Credential( + "", "", "".toCharArray() + ) + + val settings = MongoClientSettings.builder() + .applyToClusterSettings { builder: ClusterSettings.Builder -> + builder.hosts( + listOf(ServerAddress("", )) + ) + } + .credential(credential) + .build() + + val mongoClient = MongoClient.create(settings) + + .. replacement:: authentication-guide-reference + + To learn more about specifying authentication mechanisms, see the :ref `kotlin-sync-auth` + section. + + .. replacement:: verify-authentication-mechanism-anchor + + .. _kotlin-sync-verify-auth-mechanism: + + .. replacement:: authsource-param-code-block + + .. code-block:: kotlin + :copyable: false + + val mongoClient = MongoClient.create("mongodb://:@:/?authSource=users"); + + .. replacement:: dns-resolution-anchor + + .. _kotlin-sync-dns-resolution-error: + + .. replacement:: dns-error-message + + .. code-block:: none + :copyable: false + + com.mongodb.MongoSocketWriteException: Exception sending message + + .. replacement:: check-the-number-of-connections-anchor + + .. _kotlin-sync-connection-num-connections: + + .. replacement:: mongo-client-class + + ``MongoClient`` + + .. replacement:: max-pool-size-param + + ``maxPoolSize`` + + .. replacement:: max-pool-size-default + + ``100`` + + .. replacement:: max-idle-time-param + + ``maxIdleTimeMS`` + + .. replacement:: scram-failure-error + + .. code-block:: + + Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + + .. replacement:: check-credentials-formatting-anchor + + .. _kotlin-suync-troubleshooting-connection-string-auth: + + .. replacement:: connection-pools-learn-more + + To learn more about how connection pooling works in the driver, see the + :ref:`Connection Pools ` page. + +.. _kotlin-sync-timeout-errors: + +Timeout Errors +-------------- + +When you send messages through the driver to the server, sometimes the +messages take a while to respond. When this happens, you might receive an error +message similar to one of the following 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 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 the driver +maintains a connection to a MongoDB instance. For more information about these +parameters, see :ref:`Connection Pool Settings `. + +.. _kotlin-sync-server-selection-errors: + +Server Selection Timeout Exceptions +----------------------------------- + +Your application might not be able to complete a request even when some servers +are available, causing the driver to return a server selection timeout +exception. + +This exception is of type ``MongoTimeoutException``. The following +shows a sample of the exception that occurs if you attempt to send a +request to a replica set in which the primary is not reachable: + +.. code-block:: none + + com.mongodb.MongoTimeoutException: + Timed out while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}. + Client view of cluster state is + {type=REPLICA_SET, + servers=[ + {address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27018, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}}, + {address=localhost:27019, type=REPLICA_SET_SECONDARY, roundTripTime=15.0 ms, state=CONNECTED} + ] + } + +The error includes a view of the cluster state that describes the +connection state of each node, which can help you identify the source of +your connection issue. + +In the preceding error, the only connected server, ``localhost:27019``, +is a secondary node. Because of this, the request times out as the +driver is unable to select a server that satisfies the read preference +of ``primary``. In this situation, you can still perform read operations +against the connected secondary node if you set the read preference to +``secondary``, ``secondaryPreferred``, or ``nearest``. + +You can also specify the ``serverSelectionTimeoutMS`` connection option +to adjust the amount of time in which the driver must select a server. To +learn more, see the :ref:`kotlin-sync-connection-options` guide. + +.. _kotlin-sync-miscellaneous-errors: + +Miscellaneous Errors +-------------------- + +This section shows connection errors that do not fall into a broader category. + +Monitor Thread Exception +~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + :copyable: false + + INFO: Exception in monitor thread while connecting to server ssc-cluster-01-shard-00-02.9cbnp.mongodb.net:27017 + +This log line indicates that the monitor that continuously +checks the status of each replica set member or ``mongos`` server failed to +contact one of the nodes or servers. This is an expected message during server +maintenance operations and can be safely ignored. + +Certificate Request Exception +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: none + :copyable: false + + javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request + +This is a known issue in certain versions of the JDK that can occur when +attempting to connect by using the TLS 1.3 protocol. + +If you encounter this error when connecting to your MongoDB instance or +cluster, update your JDK to one of the following patch versions or newer: + +- JDK 11.0.7 +- JDK 13.0.3 +- JDK 14.0.2 + +To learn more about this issue, see the +`issue description `__ +in the OpenJDK Bug system tracker issue. + +.. _kotlin-sync-debugging-tips: + +Debugging Tips +-------------- + +While not related to a specific error message, this section includes +information that can help in the process of troubleshooting connection +issues. + +Verbose Logging for TLS/SSL +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +You can use the ``-Djavax.net.debug=all`` system property to enable +debug-level logging related to all connections, including those +established by using TLS/SSL. + +Enabling debug-level logging can help you diagnose the root problem of +connection issues. To learn more about the TLS/SSL logging messages, +see the `Debugging SSL/TLS Connections `__ +Java documentation. \ No newline at end of file From 41ec6b4417702052df90f35b765b6cb7264707b1 Mon Sep 17 00:00:00 2001 From: Angela Date: Tue, 8 Jul 2025 14:43:42 -0400 Subject: [PATCH 2/8] fix typos/broken links --- .../connect/{connection-pools => connection-pools.txt} | 0 source/connect/connection-troubleshooting.txt | 9 +++++---- 2 files changed, 5 insertions(+), 4 deletions(-) rename source/connect/{connection-pools => connection-pools.txt} (100%) diff --git a/source/connect/connection-pools b/source/connect/connection-pools.txt similarity index 100% rename from source/connect/connection-pools rename to source/connect/connection-pools.txt diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index ea5da166..52434f98 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -29,7 +29,7 @@ Connection Troubleshooting - The :ref:`Issues & Help ` page for information about reporting bugs, contributing to the driver, and finding more resources - - The `:community-forum:`MongoDB Community Forums ` for + - The :community-forum:`MongoDB Community Forums ` for questions, discussions, or general technical support .. replacement:: server-selection-timeout-error @@ -45,7 +45,7 @@ Connection Troubleshooting .. replacement:: multiple-hosts-connection-guide-link - To learn how to specify multiple replica set hosts, see + To learn how to specify multiple replica set hosts, see the :ref:`kotlin-sync-connect-replica-set` section of the Connection Guide. .. replacement:: configure-firewall-anchor @@ -106,7 +106,7 @@ Connection Troubleshooting .. replacement:: authentication-guide-reference - To learn more about specifying authentication mechanisms, see the :ref `kotlin-sync-auth` + To learn more about specifying authentication mechanisms, see the :ref`kotlin-sync-auth` section. .. replacement:: verify-authentication-mechanism-anchor @@ -159,7 +159,7 @@ Connection Troubleshooting .. replacement:: check-credentials-formatting-anchor - .. _kotlin-suync-troubleshooting-connection-string-auth: + .. _kotlin-sync-troubleshooting-connection-string-auth: .. replacement:: connection-pools-learn-more @@ -187,6 +187,7 @@ message similar to one of the following messages: If you receive one of these errors, try the following methods to resolve the issue. + Set ``maxConnectionTimeoutMS`` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 81e6d2464ec5a720744d6878c084ceca7ae38670 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 10:08:18 -0400 Subject: [PATCH 3/8] lm feedback --- source/connect/connection-options.txt | 6 ------ source/connect/connection-pools.txt | 4 +++- source/connect/connection-troubleshooting.txt | 2 +- 3 files changed, 4 insertions(+), 8 deletions(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 6144d81e..cc221a93 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -4,12 +4,6 @@ Specify Connection Options ========================== -.. contents:: On this page - :local: - :backlinks: none - :depth: 2 - :class: singlecol - .. facet:: :name: genre :values: reference diff --git a/source/connect/connection-pools.txt b/source/connect/connection-pools.txt index e83fa767..e8b95f19 100644 --- a/source/connect/connection-pools.txt +++ b/source/connect/connection-pools.txt @@ -11,4 +11,6 @@ Connection Pools :class: singlecol -.. _kotlin-sync-connection-pool-settings: \ No newline at end of file +.. _kotlin-sync-connection-pool-settings: + +.. TODO \ No newline at end of file diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 52434f98..06fe1a59 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -106,7 +106,7 @@ Connection Troubleshooting .. replacement:: authentication-guide-reference - To learn more about specifying authentication mechanisms, see the :ref`kotlin-sync-auth` + To learn more about specifying authentication mechanisms, see the :ref:`kotlin-sync-auth` section. .. replacement:: verify-authentication-mechanism-anchor From 27aab4e367bde3ca9d0266766f2e4456b83cbee8 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 11:00:30 -0400 Subject: [PATCH 4/8] fix toc --- source/connect.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect.txt b/source/connect.txt index 0b5900f2..4b16afb5 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -24,7 +24,7 @@ Connection Guide Create a MongoClient Choose a Connection Target - Connection Options + Connection Options AWS Lambda Connection Troubleshooting From e79b211df99088fc3fb82c4ccaded1a87776e90a Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 11:10:51 -0400 Subject: [PATCH 5/8] fix toc again --- source/connect.txt | 2 -- 1 file changed, 2 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 4b16afb5..ca6d1a99 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -19,8 +19,6 @@ Connection Guide :keywords: client, ssl, tls, localhost .. toctree:: - :titlesonly: - :maxdepth: 1 Create a MongoClient Choose a Connection Target From 9b3436c5b794fdfbd5a3eab16c01a61af87a9938 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 11:22:05 -0400 Subject: [PATCH 6/8] attempt error fix --- source/connect/connection-options.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index cc221a93..f01765be 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -20,7 +20,7 @@ Specify Connection Options Connection Pools .. /connect/network-compression -.. /connect/server-selection +.. /connect/server-selection Overview -------- From 0a56b512da6eb71640541623971795706d3f4e8a Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 11:46:23 -0400 Subject: [PATCH 7/8] Fix toc --- snooty.toml | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/snooty.toml b/snooty.toml index 1f20e7e9..1c0786eb 100644 --- a/snooty.toml +++ b/snooty.toml @@ -8,14 +8,16 @@ intersphinx = [ ] toc_landing_pages = [ - "/write-operations", - "/read", "/connect", "/indexes", - "work-with-indexes", + "/work-with-indexes", "/data-formats", "/builders", "/aggregation", + "/connect/connection-options", + "/logging-and-monitoring", + "/databases-and-collections" + "/api" ] sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/" From c39c0498ccf1e1e09bbdfb4c80d9870963597187 Mon Sep 17 00:00:00 2001 From: Angela Date: Wed, 9 Jul 2025 11:53:54 -0400 Subject: [PATCH 8/8] Fix build error --- snooty.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/snooty.toml b/snooty.toml index 1c0786eb..752e3cee 100644 --- a/snooty.toml +++ b/snooty.toml @@ -16,7 +16,7 @@ toc_landing_pages = [ "/aggregation", "/connect/connection-options", "/logging-and-monitoring", - "/databases-and-collections" + "/databases-and-collections", "/api" ]