Docsp 29488 - Add Connection Troubleshooting Guide

source/connection-troubleshooting.txt

@@ -0,0 +1,343 @@
+.. _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 is a general message indicating that the driver
+cannot connect to a server on the specified hostname or port. 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 ::<IP address>:<port>
+
+The following sections describe actions you can take to potentially resolve the
+issue.
+
+Start MongoDB in IPv6 Mode
+--------------------------
+
+In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both
+the client and host support both. 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.
+
+Use IPv4 with Your Mongo Client
+-------------------------------
+
+In Node.js v17 and later, the DNS resolver uses ``IPv6`` by default when both
+the client and host support both. 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.
+
+Increase 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.
+
+Consider the following example that creates a client and attempts to connect to
+a local deployment:
+
+.. literalinclude:: /code-snippets/faq/econnresetWithClientConnect-example.js
+  :language: javascript
+  :linenos:
+
+This operation can create a maximum number of 5000 connections as indicated by
+the inclusion of ``maxPoolSize`` on the URI. If the operating system has a file
+descriptor limit of 4000, this can cause an ``ECONNRESET`` error.
+
+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.
+
+.. note::
+
+   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 "P@assword":
+
+   .. code-block:: none
+
+      password = "P%40ssword"
+
+.. _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 User Permissions
+----------------------
+
+Verify that you've accessed the MongoDB deployment with the correct user. The driver
+might generate an error message if you are using a user that does not have
+permissions to send the message.
+
+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 system. For more information about how to configure RBAC in MongoDB,
+see :manual:`Default MongoDB Port </core/authorization/>`.
+
+Verify the User Is in the Authentication Database
+-------------------------------------------------
+
+Verify the user is in the correct authentication database. For more
+information about the authentication database, see
+:ref:`Authentication Error <node-troubleshooting-connection-admin>`.
+
+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:`Connection Error <node-troubleshooting-connection-firewall>`.
+
+.. _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:`Error Sending Message <node-troubleshooting-connection-number-connections>`.
+
+Timeout Error
+~~~~~~~~~~~~~
+
+Sometimes when you send a request through the driver to the server, the request
+times 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
+--------------------
+
+To prevent the driver from hanging during connection or to prevent the
+driver from spending too much time attempting to reach unreachable replica set
+nodes, you can set the ``connectTimeoutMS`` option of your
+:ref:`connection options <node-connection-options>`.
+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 is on the other side of the planet and 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:`Error Sending Message <node-troubleshooting-connection-number-connections>`.