Skip to content

DOCSP-48389 Connection Troubleshooting Revisions #1068

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 11 commits into from
Apr 22, 2025
Merged

DOCSP-48389 Connection Troubleshooting Revisions #1068

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
0000484
DOCSP-48389 Connection Troubleshooting Revisions
lindseymoore Apr 1, 2025
cbafc30
tech question
lindseymoore Apr 1, 2025
39adc2e
edits
lindseymoore Apr 1, 2025
bc5ece3
tech review
lindseymoore Apr 14, 2025
071c0e1
edit
lindseymoore Apr 14, 2025
234aebb
remov
lindseymoore Apr 14, 2025
0dcdb92
technical review
lindseymoore Apr 16, 2025
ce22b4a
security comment
lindseymoore Apr 18, 2025
4cab153
Merge branch 'comp-cov' of github.com:mongodb/docs-node into DOCSP-48389
lindseymoore Apr 18, 2025
fbe3261
JS review
lindseymoore Apr 22, 2025
342f124
edit
lindseymoore Apr 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 27 additions & 64 deletions source/connect/connection-troubleshooting.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,36 +26,20 @@
with MongoDB or the driver, visit the following resources:

- The :ref:`Issues & Help <node-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 <https://community.mongodb.com>`__ for
questions, discussions, or general technical support

Connection 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``:

.. code-block:: none
:copyable: false

Error: couldn't connect to server 127.0.0.1:27017
If the driver cannot connect to the specified host, you might get an
``MongoServerSelectionError``.

The following sections describe actions 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
Expand All @@ -64,18 +48,28 @@
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 </reference/default-mongodb-port/>`.
:manual:`Default MongoDB Port </reference/default-mongodb-port/>` in the
{+mdb-server+} manual.

.. warning::

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 Network Access section of
the Atlas UI. To learn more about how to configure your IP Access List,
see the :atlas:`Configure IP Access List Entries </security/ip-access-list/>`
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
Expand All @@ -85,8 +79,8 @@
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
Expand All @@ -112,7 +106,7 @@
----------------

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
Expand All @@ -133,7 +127,9 @@
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::

Expand All @@ -150,8 +146,7 @@
.. code-block:: none
:copyable: false

Command failed with error 18 (AuthenticationFailed): 'Authentication
failed.' on server <hostname>:<port>.
MongoServerError: bad auth : authentication failed

Check failure on line 149 in source/connect/connection-troubleshooting.txt

View workflow job for this annotation

GitHub Actions / TDBX Vale rules 

[vale] reported by reviewdog 🐶
[MongoDB.NegativeWords] Use 'Use serious or add an explanation' instead of the negative word 'bad'.

Raw Output:
{"message": "[MongoDB.NegativeWords] Use 'Use serious or add an explanation' instead of the negative word 'bad'.", "location": {"path": "source/connect/connection-troubleshooting.txt", "range": {"start": {"line": 149, "column": 22}}}, "severity": "ERROR"}

.. code-block:: none
:copyable: false
Expand All @@ -169,12 +164,13 @@
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 <node-connection-uri>` in the Connection Guide.
see the :ref:`Connection URI <node-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
Expand Down Expand Up @@ -216,10 +212,6 @@
const uri = "mongodb://<db_username>:<db_password>@<hostname>:<port>/?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
---------------------

Expand Down Expand Up @@ -271,27 +263,6 @@
:ref:`Connection Pool Overview <node-faq-connection-pool>`
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 <node-troubleshooting-connection-number-connections>`
in the Error Sending Message section.

Timeout Error
-------------

Expand All @@ -313,7 +284,7 @@
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 </reference/connection-string/#timeout-options>` in
the Server manual.

Expand All @@ -331,14 +302,6 @@
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 <node-troubleshooting-connection-number-connections>`
in the Error Sending Message section.

Client Disconnect While Running Operation
-----------------------------------------

Expand Down
Loading