diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index e81ace34a..653b5fef7 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -26,36 +26,20 @@ 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 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 @@ -64,18 +48,28 @@ 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:: 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 ` +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 +79,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 +106,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 +127,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 +146,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 @@ -169,12 +164,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 @@ -216,10 +212,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 --------------------- @@ -271,27 +263,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 ------------- @@ -313,7 +284,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. @@ -331,14 +302,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 -----------------------------------------