Docsp 29488 - Add Connection Troubleshooting Guide

source/connection-troubleshooting.txt

@@ -0,0 +1,336 @@
+.. _node-connection-troubleshooting:
+
+==========================
+Connection Troubleshooting
+==========================
+
+.. contents:: On this page
+   :local:
+   :backlinks: none
+   :depth: 2
+   :class: singlecol
+
+This page offers potential solutions to issues you might encounter when
+using the {+driver-long+} to connect to a MongoDB deployment.
+
+.. note::
+
+   This page addresses only connection issues. If you encounter any other issues
+   with MongoDB or the driver, visit the following resources:
+
+   - The :ref:`Frequently Asked Questions (FAQ) <node-faq>` for the
+     {+driver-short+}
+   - The :ref:`Issues & Help <node-issues-help>` page, which has
+     information about reporting bugs, contributing to the driver, and 
+     finding additional 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
+
+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
+-----------------------
+
+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/>`.
+
+.. warning::
+
+   Do not open a port in your firewall unless you are sure it's the port
+   used by your MongoDB deployment.
+
+ECONNREFUSED Error
+~~~~~~~~~~~~~~~~~~
+
+If the connection is refused when the driver attempts to connect to the MongoDB
+instance, it generates this error message:
+
+.. code-block:: none
+   :copyable: false
+
+   MongoServerSelectionError: connect ECONNREFUSED <IPv6 address>:<port>
+
+The following sections describe actions you can take to potentially resolve the
+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
+the client and host support both. For example, if MongoDB uses IPv4 and your
+client uses IPv6, the driver returns the previous error message.
+
+You can configure your MongoDB deployment to use ``IPv6`` mode when starting
+with ``mongod`` or ``mongos``. For more information about how to specify
+``IPv6`` mode, see
+:manual:`IP Binding </core/security-mongodb-configuration/>` in the server
+manual.
+
+As an alternative, you can explicitly use ``IPv4`` with your client by
+specifying ``family: 4`` as an
+`option to your MongoClient <{+api+}/interfaces/MongoClientOptions.html#family>`__.
+
+.. code-block:: js
+
+   const client = new MongoClient(uri, {
+     family: 4,
+   });
+
+ECONNRESET Error
+~~~~~~~~~~~~~~~~
+
+If the connection is reset when the driver calls ``client.connect()``, it
+generates this error message:
+
+.. code-block:: none
+   :copyable: false
+
+   MongoServerSelectionError: connect ECONNRESET ::<IP address>:<port>
+
+The following section describes a method that may help resolve the issue.
+
+Control the Number of File Descriptors
+--------------------------------------
+
+A file descriptor is a unique identifier associated with an open process. In most
+operating systems, each open connection from the driver is associated with a
+file descriptor. Operating systems typically have a limit on the number of file
+descriptors used by a single process. An ``ECONNRESET`` error can occur
+if the number of connections exceeds this limit.
+
+You can set the maxmimum 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.
+
+.. warning::
+
+   Changing the configuration of your operating system should always be done
+   with caution.
+
+Authentication Error
+~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} can fail to connect to a MongoDB instance if
+the authorization is not configured correctly. If you are using ``SCRAM-SHA-256``
+for authentication and the driver fails to connect, the driver might raise an
+error message similar to one of the following messages:
+
+.. code-block:: none
+   :copyable: false
+
+   Command failed with error 18 (AuthenticationFailed): 'Authentication
+   failed.' on server <hostname>:<port>.
+
+.. code-block:: none
+   :copyable: false
+
+   connection() error occurred during connection handshake: auth error:
+   sasl conversation error: unable to authenticate using mechanism
+   "SCRAM-SHA-256": (AuthenticationFailed) Authentication failed.
+
+The following sections describe actions you can take to potentially resolve the
+issue.
+
+.. _node-troubleshooting-connection-string-auth:
+
+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``.
+
+.. tip::
+
+   For more information about connection strings,
+   see :ref:`Connection URI <node-connection-uri>` 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
+following characters, they must be
+`percent encoded <https://tools.ietf.org/html/rfc3986#section-2.1>`__:
+
+.. code-block:: none
+
+    : / ? # [ ] @
+
+The following example shows how to percent encode "#MyP@assword?":
+
+.. code-block:: javascript
+
+   console.log(encodeURIComponent('#MyP@assword?'));
+
+This results in the following output:
+
+.. code-block:: none
+
+   "%23MyP%40assword%3F"
+
+.. _node-troubleshooting-connection-admin:
+
+Verify the User Is in the Authentication Database
+-------------------------------------------------
+
+To successfully authenticate a connection by using a username and password with
+``SCRAM-SHA-256``, 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:: javascript
+   :copyable: true
+
+   const { MongoClient } = require("mongodb");
+   const uri = "mongodb://<username>:<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
+~~~~~~~~~~~~~~~~~~~~~
+
+When the driver fails to send a command after you make a request,
+it may display the following error message:
+
+.. code-block:: none
+   :copyable: false
+
+   com.mongodb.MongoSocketWriteException: Exception sending message
+
+The following sections describe actions you can take to potentially resolve the
+issue.
+
+Check the User Permissions
+--------------------------
+
+Verify that you've accessed the MongoDB deployment with the correct user. The
+term "message" in the error can be a command sent by the driver.
+If you are using a user that doesn't have permissions to send the command, the
+driver could generate this error.
+
+Also ensure that the user has the appropriate permissions for the message you
+are sending. MongoDB uses Role-Based Access Control (RBAC) to control access
+to a MongoDB deployment. For more information about how to configure RBAC in MongoDB,
+see :manual:`Default MongoDB Port </core/authorization/>`.
+
+Configure Your Firewall
+-----------------------
+
+The firewall needs to have an open port for communicating with the MongoDB
+instance. For more information about configuring the firewall, see
+:ref:`Configure Your Firewall <node-troubleshooting-connection-firewall>` in
+the Connection Error section.
+
+.. _node-troubleshooting-connection-number-connections:
+
+Check the Number of Connections
+-------------------------------
+
+Each ``MongoClient`` instance supports a maximum number of concurrent open
+connections in its connection pool. You can configure the parameter ``maxPoolSize``
+which defines this limit. The default value is ``100``. 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.
+
+For more information about how connection pooling works, see
+:ref:`How Does Connection Pooling Work in the Node Driver? <node-faq-connection-pool>`
+in the FAQ.
+
+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
+-------------------------------
+
+If you need to create more open connections, increase ``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
+~~~~~~~~~~~~~
+
+When the network is not able to deliver a request from the driver to the server
+quickly enough, it can time out. When this happens, you might receive an error message
+similar to the following message:
+
+.. code-block:: none
+   :copyable: false
+
+   timed out while checking out a connection from connection pool: context canceled
+
+If you receive this error, try the following action to resolve the
+issue.
+
+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
+:manual:`Timeout Options </reference/connection-string/#timeout-options>` in
+the server manual.
+
+You should ensure the ``connectTimeoutMS`` setting is not lower than
+the highest network latency you have to a member of the set. If one of the
+secondary members has a latency of 10000 milliseconds, setting the
+``connectTimeoutMS`` to 9000 prevents the driver from ever connecting to that
+member.
+
+The following example sets ``connectTimeoutMS`` to 10000 milliseconds.
+
+.. code-block:: javascript
+
+   const client = new MongoClient(uri, {
+     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.