From 00004844e41ad03b3325fa8f3b9911464a769f71 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 1 Apr 2025 16:37:19 -0400 Subject: [PATCH 01/10] DOCSP-48389 Connection Troubleshooting Revisions --- source/connect/connection-troubleshooting.txt | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index e81ace34a..17f7db12c 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -26,8 +26,8 @@ using the {+driver-long+} to connect to a MongoDB deployment. with MongoDB or the driver, visit the following resources: - The :ref:`Issues & Help ` page, which has - information about reporting bugs, contributing to the driver, and - finding more resources + information about how to report bugs, contribute to the driver, and + find more resources - The `MongoDB Community Forums `__ for questions, discussions, or general technical support From cbafc30969c351e9ad785867ac6ac32174db9bb9 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 1 Apr 2025 16:38:34 -0400 Subject: [PATCH 02/10] tech question --- source/connect/connection-troubleshooting.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 17f7db12c..e2d6160da 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -88,7 +88,7 @@ issue. Ensure MongoDB and Your Client Use the Same Protocol ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both +In Node.js v?.17 and later, the DNS resolver uses ``IPv6`` by default when both the client and host support both. For example, if MongoDB uses IPv4 and your client uses IPv6, the driver returns the previous error message. From 39adc2e9a9653b47188c46f39a69bb9f4206b5c1 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 1 Apr 2025 17:04:25 -0400 Subject: [PATCH 03/10] edits --- source/connect/connection-troubleshooting.txt | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index e2d6160da..6fdb05218 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -88,7 +88,7 @@ issue. Ensure MongoDB and Your Client Use the Same Protocol ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -In Node.js v?.17 and later, the DNS resolver uses ``IPv6`` by default when both +In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both the client and host support both. For example, if MongoDB uses IPv4 and your client uses IPv6, the driver returns the previous error message. @@ -169,12 +169,13 @@ Check Your Connection String ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ An invalid connection string is the most common cause of authentication -issues when attempting to connect to MongoDB using ``SCRAM-SHA-256``. +issues when you attempt to connect to MongoDB by using ``SCRAM-SHA-256``. .. tip:: For more information about connection strings, - see :ref:`Connection URI ` in the Connection Guide. + see the :ref:`Connection URI ` section in the Connection + Guide. If your connection string contains a username and password, ensure that they are in the correct format. If the username or password includes any of the @@ -313,7 +314,7 @@ Set connectTimeoutMS The driver may hang when it's unable to establish a connection because it takes too long attempting to reach unreachable replica set nodes. You can limit the time the driver spends attempting to establish the connection by using the -``connectTimeMS`` setting. To learn more about this setting, see the +``connectTimeoutMS`` setting. To learn more about this setting, see the :manual:`Timeout Options ` in the Server manual. From bc5ece300f5e55695db14d0633ffe31cf84e637a Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 14 Apr 2025 18:17:51 -0400 Subject: [PATCH 04/10] tech review --- source/connect/connection-troubleshooting.txt | 73 ++++++------------- 1 file changed, 21 insertions(+), 52 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 6fdb05218..bd68eafed 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -31,31 +31,20 @@ using the {+driver-long+} to connect to a MongoDB deployment. - The `MongoDB Community Forums `__ for questions, discussions, or general technical support -Connection Error +Server SSL Error ---------------- -The following error message indicates that the driver cannot connect to a server -on the specified hostname or port. Multiple situations can generate this error -message. In this sample error message, the hostname is ``127.0.0.1`` and the -port is ``27017``: +If the driver cannot securely connect to the specified host, you may get an +error message similar to the following: .. code-block:: none :copyable: false - Error: couldn't connect to server 127.0.0.1:27017 + MongoServerSelectionError: SSL alert internal error -The following sections describe actions you can take to potentially resolve the +The following section describes an action you can take to potentially resolve the issue. -.. _node-troubleshooting-connection-string-port: - -Check Your Connection String -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Verify that the hostname and port number in the connection string are both -accurate. The default port value for a MongoDB instance is -``27017``, but you can configure MongoDB to communicate on another port. - .. _node-troubleshooting-connection-firewall: Configure Your Firewall @@ -71,11 +60,19 @@ more about the default ports MongoDB uses and how to change them, see Do not open a port in your firewall unless you are sure it's the port used by your MongoDB deployment. +Check Your Network Access List +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Verify that your IP Address is listed in the IP Access List for your cluster. +You can find your IP Access List in the :guilabel:`Network Access` section of +the Atlas UI. To learn more about how to configure your IP Access List, +see the :atlas:`` guide in the Atlas documentation. + ECONNREFUSED Error ------------------ If the connection is refused when the driver attempts to connect to the MongoDB -instance, it generates this error message: +instance, it generates an error message similar to the following: .. code-block:: none :copyable: false @@ -85,8 +82,8 @@ instance, it generates this error message: The following sections describe actions you can take to potentially resolve the issue. -Ensure MongoDB and Your Client Use the Same Protocol -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Ensure MongoDB and Your Client Use the Same IP Address +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both the client and host support both. For example, if MongoDB uses IPv4 and your @@ -112,7 +109,7 @@ ECONNRESET Error ---------------- If the connection is reset when the driver calls ``client.connect()``, it -generates this error message: +generates an error message similar to the following: .. code-block:: none :copyable: false @@ -133,7 +130,9 @@ if the number of connections exceeds this limit. You can set the maximum number of connections by setting ``maxPoolSize``. To resolve this error, you can decrease the number of maximum allowed connections by setting the value of ``maxPoolSize``. Alternatively, you could increase the -file descriptor limit in your operating system. +file descriptor limit in your operating system. To learn more about how to set +``maxPoolSize``, see the API documentation for +`maxPoolSize <{+api+}//interfaces/MongoClientOptions.html#maxPoolSize>`__ . .. warning:: @@ -150,8 +149,7 @@ error message similar to one of the following messages: .. code-block:: none :copyable: false - Command failed with error 18 (AuthenticationFailed): 'Authentication - failed.' on server :. + MongoServerError: bad auth : authentication failed .. code-block:: none :copyable: false @@ -272,27 +270,6 @@ For more information about how connection pooling works, see the :ref:`Connection Pool Overview ` in the Connection Pools page. -Too Many Open Connections -------------------------- - -The driver creates the following error message when it attempts to open a -connection, but it's reached the maximum number of connections: - -.. code-block:: none - :copyable: false - - connection refused because too many open connections - -The following section describes a method that may help resolve the issue. - -Check the Number of Connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To create more open connections, increase the value of ``maxPoolSize``. For more -information about checking the number of connections, see -:ref:`Check the Number of Connections ` -in the Error Sending Message section. - Timeout Error ------------- @@ -332,14 +309,6 @@ The following example sets ``connectTimeoutMS`` to 10000 milliseconds. connectTimeoutMS: 10000, }); -Check the Number of Connections -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The number of connections to the server may exceed ``maxPoolSize``. For more -information about checking the number of connections, see -:ref:`Check the Number of Connections ` -in the Error Sending Message section. - Client Disconnect While Running Operation ----------------------------------------- From 071c0e1c9b1df4f1b81fc3ff09b51caa45e3067d Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 14 Apr 2025 18:22:08 -0400 Subject: [PATCH 05/10] edit --- source/connect/connection-troubleshooting.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index bd68eafed..56dc376b0 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -35,7 +35,7 @@ Server SSL Error ---------------- If the driver cannot securely connect to the specified host, you may get an -error message similar to the following: +error message that contains the following: .. code-block:: none :copyable: false From 234aebb3198e533540ebc48e49a1f506fced4bc5 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Mon, 14 Apr 2025 18:43:26 -0400 Subject: [PATCH 06/10] remov --- source/connect/connection-troubleshooting.txt | 4 ---- 1 file changed, 4 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 56dc376b0..08b8c642e 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -215,10 +215,6 @@ database: const uri = "mongodb://:@:/?authSource=users"; const client = new MongoClient(uri); -You can check if this is the issue by attempting to connect to a MongoDB -instance hosted on the local machine with the same code. A deployment on -the same machine doesn't require any authorization to connect. - Error Sending Message --------------------- From 0dcdb9259e5732b34e30b296bd49d4eb1fa4954f Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Wed, 16 Apr 2025 15:22:45 -0400 Subject: [PATCH 07/10] technical review --- source/connect/connection-troubleshooting.txt | 16 ++++++---------- 1 file changed, 6 insertions(+), 10 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 08b8c642e..2ef3d4a60 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -31,18 +31,13 @@ using the {+driver-long+} to connect to a MongoDB deployment. - The `MongoDB Community Forums `__ for questions, discussions, or general technical support -Server SSL Error +Connection Error ---------------- If the driver cannot securely connect to the specified host, you may get an -error message that contains the following: +``MongoServerSelectionError``. -.. code-block:: none - :copyable: false - - MongoServerSelectionError: SSL alert internal error - -The following section describes an action you can take to potentially resolve the +The following sections describes actions you can take to potentially resolve the issue. .. _node-troubleshooting-connection-firewall: @@ -64,9 +59,10 @@ Check Your Network Access List ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Verify that your IP Address is listed in the IP Access List for your cluster. -You can find your IP Access List in the :guilabel:`Network Access` section of +You can find your IP Access List in the Network Access section of the Atlas UI. To learn more about how to configure your IP Access List, -see the :atlas:`` guide in the Atlas documentation. +see the :atlas:`Configure IP Access List Entries ` +guide in the Atlas documentation. ECONNREFUSED Error ------------------ From ce22b4a630614df3ecf9db30a41d09b53c171f5e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Fri, 18 Apr 2025 13:46:24 -0400 Subject: [PATCH 08/10] security comment --- source/connect/connection-troubleshooting.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 2ef3d4a60..f6822164f 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -34,7 +34,7 @@ using the {+driver-long+} to connect to a MongoDB deployment. Connection Error ---------------- -If the driver cannot securely connect to the specified host, you may get an +If the driver cannot connect to the specified host, you may get an ``MongoServerSelectionError``. The following sections describes actions you can take to potentially resolve the From fbe32614a1d0feb38209559705590e21b903e187 Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 14:53:21 -0400 Subject: [PATCH 09/10] JS review --- source/connect/connection-troubleshooting.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index f6822164f..437320dd7 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -34,10 +34,10 @@ using the {+driver-long+} to connect to a MongoDB deployment. Connection Error ---------------- -If the driver cannot connect to the specified host, you may get an +If the driver cannot connect to the specified host, you might get an ``MongoServerSelectionError``. -The following sections describes actions you can take to potentially resolve the +The following sections describe actions you can take to potentially resolve the issue. .. _node-troubleshooting-connection-firewall: @@ -128,7 +128,7 @@ resolve this error, you can decrease the number of maximum allowed connections by setting the value of ``maxPoolSize``. Alternatively, you could increase the file descriptor limit in your operating system. To learn more about how to set ``maxPoolSize``, see the API documentation for -`maxPoolSize <{+api+}//interfaces/MongoClientOptions.html#maxPoolSize>`__ . +`maxPoolSize <{+api+}/interfaces/MongoClientOptions.html#maxPoolSize>`__ . .. warning:: From 342f12429bb30b1211c14290eeb0492db60e4b3e Mon Sep 17 00:00:00 2001 From: Lindsey Moore Date: Tue, 22 Apr 2025 14:59:53 -0400 Subject: [PATCH 10/10] edit --- source/connect/connection-troubleshooting.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 437320dd7..653b5fef7 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -48,7 +48,8 @@ Configure Your Firewall Verify that the ports your MongoDB deployment listens on are not blocked by a firewall on the same network. MongoDB uses port ``27017`` by default. To learn more about the default ports MongoDB uses and how to change them, see -:manual:`Default MongoDB Port `. +:manual:`Default MongoDB Port ` in the +{+mdb-server+} manual. .. warning::