Skip to content

Commit 3bfbf9c

Browse files
shuangelashuangela
authored
DOCSP-51408-connection-troubleshooting (#109)
* connection troubleshooting: * fix typos/broken links * lm feedback * fix toc * fix toc again * attempt error fix * Fix toc * Fix build error
1 parent d56dcd3 commit 3bfbf9c

File tree

6 files changed

+335
-15
lines changed

6 files changed

+335
-15
lines changed

‎snooty.toml

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -8,14 +8,16 @@ intersphinx = [
88
]
99

1010
toc_landing_pages = [
11-
"/write-operations",
12-
"/read",
1311
"/connect",
1412
"/indexes",
15-
"work-with-indexes",
13+
"/work-with-indexes",
1614
"/data-formats",
1715
"/builders",
1816
"/aggregation",
17+
"/connect/connection-options",
18+
"/logging-and-monitoring",
19+
"/databases-and-collections",
20+
"/api"
1921
]
2022

2123
sharedinclude_root = "https://raw.githubusercontent.com/10gen/docs-shared/main/"

‎source/connect.txt

Lines changed: 2 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,15 +19,12 @@ Connection Guide
1919
:keywords: client, ssl, tls, localhost
2020

2121
.. toctree::
22-
:titlesonly:
23-
:maxdepth: 1
2422

2523
Create a MongoClient </connect/mongoclient>
2624
Choose a Connection Target </connect/connection-targets>
27-
Connection Options </connect/connection-options>
25+
Connection Options </connect/connection-options>
2826
AWS Lambda <https://www.mongodb.com/docs/atlas/manage-connections-aws-lambda/>
29-
30-
.. /connect/connection-troubleshooting
27+
Connection Troubleshooting </connect/connection-troubleshooting>
3128

3229
Overview
3330
--------

‎source/connect/connection-options.txt

Lines changed: 2 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -4,12 +4,6 @@
44
Specify Connection Options
55
==========================
66

7-
.. contents:: On this page
8-
:local:
9-
:backlinks: none
10-
:depth: 2
11-
:class: singlecol
12-
137
.. facet::
148
:name: genre
159
:values: reference
@@ -23,9 +17,10 @@ Specify Connection Options
2317

2418
Stable API </connect/stable-api>
2519
Limit Server Execution Time </connect/csot>
20+
Connection Pools </connect/connection-pools>
2621

2722
.. /connect/network-compression
28-
.. /connect/server-selection
23+
.. /connect/server-selection
2924

3025
Overview
3126
--------

‎source/connect/connection-pools.txt

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
.. _kotlin-sync-connection-pools:
2+
3+
================
4+
Connection Pools
5+
================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
14+
.. _kotlin-sync-connection-pool-settings:
15+
16+
.. TODO

‎source/connect/connection-targets.txt

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,8 @@ deployment:
7070
:end-before: end-connect-local
7171
:dedent:
7272

73+
.. _kotlin-sync-connect-replica-set:
74+
7375
Replica Sets
7476
------------
7577

‎source/connect/connection-troubleshooting.txt

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
.. _kotlin-sync-connection-troubleshooting:
2+
3+
==========================
4+
Connection Troubleshooting
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code example, disconnected, deployment
19+
20+
.. sharedinclude:: dbx/connection-troubleshooting.rst
21+
22+
.. replacement:: non-connection-issue-callout
23+
24+
.. note::
25+
26+
This page addresses only connection issues. If you encounter other
27+
issues when using MongoDB or the driver, visit the following resources:
28+
29+
- The :ref:`Issues & Help <kotlin-sync-issues-and-help>` page for
30+
information about reporting bugs, contributing to the driver, and
31+
finding more resources
32+
- The :community-forum:`MongoDB Community Forums </tag/kotlin>` for
33+
questions, discussions, or general technical support
34+
35+
.. replacement:: server-selection-timeout-error
36+
37+
.. code-block:: none
38+
:copyable: false
39+
40+
Error: couldn't connect to server 127.0.0.1:27017
41+
42+
.. replacement:: check-connection-string-anchor
43+
44+
.. _kotlin-sync-connection-string-port:
45+
46+
.. replacement:: multiple-hosts-connection-guide-link
47+
48+
To learn how to specify multiple replica set hosts, see the
49+
:ref:`kotlin-sync-connect-replica-set` section of the Connection Guide.
50+
51+
.. replacement:: configure-firewall-anchor
52+
53+
.. _kotlin-sync-connection-firewall:
54+
55+
.. replacement:: authentication-error-anchor
56+
57+
.. _kotlin-sync-authentication-error:
58+
59+
.. replacement:: scram-failure-error
60+
61+
.. code-block:: none
62+
:copyable: false
63+
64+
Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017.
65+
66+
.. replacement:: check-credentials-formatting-anchor
67+
68+
.. _kotlin-sync-connection-string-auth:
69+
70+
.. replacement:: learn-more-connection-string-admonition
71+
72+
.. tip::
73+
74+
For more information about using connection strings,
75+
see :ref:`Connection URI <kotlin-sync-connection-uri>` in the Connection Guide.
76+
77+
.. replacement:: percent-encode-example
78+
79+
.. replacement:: verify-authentication-database-anchor
80+
81+
.. _kotlin-sync-verify-auth-db:
82+
83+
.. replacement:: credentials-provider-alternative-method-description
84+
85+
If you construct a client by using a ``MongoCredential``, the builder method
86+
corresponds to the authentication mechanism. The following code shows the builder
87+
method for the ``SCRAM-SHA-256`` authentication mechanism:
88+
89+
.. code-block:: kotlin
90+
:copyable: false
91+
92+
val credential = MongoCredential.createScramSha256Credential(
93+
"<db_username>", "<authenticationDb>", "<db_password>".toCharArray()
94+
)
95+
96+
val settings = MongoClientSettings.builder()
97+
.applyToClusterSettings { builder: ClusterSettings.Builder ->
98+
builder.hosts(
99+
listOf(ServerAddress("<hostname>", <port>))
100+
)
101+
}
102+
.credential(credential)
103+
.build()
104+
105+
val mongoClient = MongoClient.create(settings)
106+
107+
.. replacement:: authentication-guide-reference
108+
109+
To learn more about specifying authentication mechanisms, see the :ref:`kotlin-sync-auth`
110+
section.
111+
112+
.. replacement:: verify-authentication-mechanism-anchor
113+
114+
.. _kotlin-sync-verify-auth-mechanism:
115+
116+
.. replacement:: authsource-param-code-block
117+
118+
.. code-block:: kotlin
119+
:copyable: false
120+
121+
val mongoClient = MongoClient.create("mongodb://<db_username>:<db_password>@<hostname>:<port>/?authSource=users");
122+
123+
.. replacement:: dns-resolution-anchor
124+
125+
.. _kotlin-sync-dns-resolution-error:
126+
127+
.. replacement:: dns-error-message
128+
129+
.. code-block:: none
130+
:copyable: false
131+
132+
com.mongodb.MongoSocketWriteException: Exception sending message
133+
134+
.. replacement:: check-the-number-of-connections-anchor
135+
136+
.. _kotlin-sync-connection-num-connections:
137+
138+
.. replacement:: mongo-client-class
139+
140+
``MongoClient``
141+
142+
.. replacement:: max-pool-size-param
143+
144+
``maxPoolSize``
145+
146+
.. replacement:: max-pool-size-default
147+
148+
``100``
149+
150+
.. replacement:: max-idle-time-param
151+
152+
``maxIdleTimeMS``
153+
154+
.. replacement:: scram-failure-error
155+
156+
.. code-block::
157+
158+
Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017.
159+
160+
.. replacement:: check-credentials-formatting-anchor
161+
162+
.. _kotlin-sync-troubleshooting-connection-string-auth:
163+
164+
.. replacement:: connection-pools-learn-more
165+
166+
To learn more about how connection pooling works in the driver, see the
167+
:ref:`Connection Pools <kotlin-sync-connection-pools>` page.
168+
169+
.. _kotlin-sync-timeout-errors:
170+
171+
Timeout Errors
172+
--------------
173+
174+
When you send messages through the driver to the server, sometimes the
175+
messages take a while to respond. When this happens, you might receive an error
176+
message similar to one of the following messages:
177+
178+
.. code-block:: none
179+
:copyable: false
180+
181+
Timed out after 30000 ms while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}.
182+
183+
.. code-block:: none
184+
:copyable: false
185+
186+
No server chosen by ReadPreferenceServerSelector{readPreference=primary} from cluster description
187+
188+
If you receive one of these errors, try the following methods to resolve the
189+
issue.
190+
191+
Set ``maxConnectionTimeoutMS``
192+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
193+
194+
The ``maxConnectionTimeoutMS`` option indicates the time the {+driver-short+} waits
195+
for a connection before timing out. The default value is ``10000``. You can
196+
increase this value or set it to ``0`` if you want the driver to never timeout.
197+
198+
Set ``maxConnectionLifeTime`` and ``maxConnectionIdleTime``
199+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
200+
201+
Consider setting ``maxConnectionLifeTime`` and
202+
``maxConnectionIdleTime``. These parameters configure how long the driver
203+
maintains a connection to a MongoDB instance. For more information about these
204+
parameters, see :ref:`Connection Pool Settings <kotlin-sync-connection-pool-settings>`.
205+
206+
.. _kotlin-sync-server-selection-errors:
207+
208+
Server Selection Timeout Exceptions
209+
-----------------------------------
210+
211+
Your application might not be able to complete a request even when some servers
212+
are available, causing the driver to return a server selection timeout
213+
exception.
214+
215+
This exception is of type ``MongoTimeoutException``. The following
216+
shows a sample of the exception that occurs if you attempt to send a
217+
request to a replica set in which the primary is not reachable:
218+
219+
.. code-block:: none
220+
221+
com.mongodb.MongoTimeoutException:
222+
Timed out while waiting for a server that matches ReadPreferenceServerSelector{readPreference=primary}.
223+
Client view of cluster state is
224+
{type=REPLICA_SET,
225+
servers=[
226+
{address=localhost:27017, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}},
227+
{address=localhost:27018, type=UNKNOWN, state=CONNECTING, exception={com.mongodb.MongoSocketOpenException: Exception opening socket}, caused by {java.net.ConnectException: Connection refused}},
228+
{address=localhost:27019, type=REPLICA_SET_SECONDARY, roundTripTime=15.0 ms, state=CONNECTED}
229+
]
230+
}
231+
232+
The error includes a view of the cluster state that describes the
233+
connection state of each node, which can help you identify the source of
234+
your connection issue.
235+
236+
In the preceding error, the only connected server, ``localhost:27019``,
237+
is a secondary node. Because of this, the request times out as the
238+
driver is unable to select a server that satisfies the read preference
239+
of ``primary``. In this situation, you can still perform read operations
240+
against the connected secondary node if you set the read preference to
241+
``secondary``, ``secondaryPreferred``, or ``nearest``.
242+
243+
You can also specify the ``serverSelectionTimeoutMS`` connection option
244+
to adjust the amount of time in which the driver must select a server. To
245+
learn more, see the :ref:`kotlin-sync-connection-options` guide.
246+
247+
.. _kotlin-sync-miscellaneous-errors:
248+
249+
Miscellaneous Errors
250+
--------------------
251+
252+
This section shows connection errors that do not fall into a broader category.
253+
254+
Monitor Thread Exception
255+
~~~~~~~~~~~~~~~~~~~~~~~~
256+
257+
.. code-block:: none
258+
:copyable: false
259+
260+
INFO: Exception in monitor thread while connecting to server ssc-cluster-01-shard-00-02.9cbnp.mongodb.net:27017
261+
262+
This log line indicates that the monitor that continuously
263+
checks the status of each replica set member or ``mongos`` server failed to
264+
contact one of the nodes or servers. This is an expected message during server
265+
maintenance operations and can be safely ignored.
266+
267+
Certificate Request Exception
268+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
269+
270+
.. code-block:: none
271+
:copyable: false
272+
273+
javax.net.ssl.SSLHandshakeException: extension (5) should not be presented in certificate_request
274+
275+
This is a known issue in certain versions of the JDK that can occur when
276+
attempting to connect by using the TLS 1.3 protocol.
277+
278+
If you encounter this error when connecting to your MongoDB instance or
279+
cluster, update your JDK to one of the following patch versions or newer:
280+
281+
- JDK 11.0.7
282+
- JDK 13.0.3
283+
- JDK 14.0.2
284+
285+
To learn more about this issue, see the
286+
`issue description <https://bugs.openjdk.java.net/browse/JDK-8236039>`__
287+
in the OpenJDK Bug system tracker issue.
288+
289+
.. _kotlin-sync-debugging-tips:
290+
291+
Debugging Tips
292+
--------------
293+
294+
While not related to a specific error message, this section includes
295+
information that can help in the process of troubleshooting connection
296+
issues.
297+
298+
Verbose Logging for TLS/SSL
299+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
300+
301+
You can use the ``-Djavax.net.debug=all`` system property to enable
302+
debug-level logging related to all connections, including those
303+
established by using TLS/SSL.
304+
305+
Enabling debug-level logging can help you diagnose the root problem of
306+
connection issues. To learn more about the TLS/SSL logging messages,
307+
see the `Debugging SSL/TLS Connections <https://docs.oracle.com/javase/8/docs/technotes/guides/security/jsse/ReadDebug.html>`__
308+
Java documentation.

0 commit comments

Comments
 (0)