DOCSP-29490: Created Connection Troubleshooting Guide (#102)

* DOCSP-29490: Initial topic creation

* PR feedback

* Further PR feedback

* Final PR adjustments

Author: DBirtolo-mdb

source/connection-troubleshooting.txt

@@ -0,0 +1,308 @@
+.. _csharp-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) <csharp-faq>` for the
+     {+driver-short+}
+   - The :ref:`Issues & Help <csharp-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.
+
+.. _csharp-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.
+
+.. _csharp-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.
+
+Authentication Error
+~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} can fail to connect to a MongoDB instance if
+the authentication mechanism is not configured correctly. If you are using ``SCRAM-SHA-256``
+or ``SCRAM-SHA-1`` 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
+
+   Authentication failed","attr":{"mechanism":"SCRAM-SHA-256","principalName":
+   "<user>","<auth database>":"<user>","client":"127.0.0.1:2012",
+   "result":"UserNotFound: Could not find user}}
+
+.. 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.
+
+.. _csharp-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 connection strings and
+``SCRAM-SHA-256`` or ``SCRAM-SHA-1``.
+
+.. tip::
+
+   For more information about connection strings,
+   see :ref:`Connection URI <csharp-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 "#MyPassword?":
+
+.. code-block:: csharp
+
+   Console.WriteLine(System.Web.HttpUtility.UrlEncode("#MyPaassword?"));
+
+This results in the following output:
+
+.. code-block:: none
+
+   %23MyPassword%3F
+
+.. _csharp-troubleshooting-connection-mongoclientsettings:
+
+Verify the MongoClientSettings Properties
+-----------------------------------------
+
+You can use a ``MongoClientSettings`` object to configure the settings when
+attempting to connect to a MongoDB deployment. You can use the ``Credential``
+property to set authentication information. If the credential information is not
+correct, you will receive authentication errors when you attempt to connect to
+your MongoDB deployment.
+
+.. _csharp-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`` or ``SCRAM-SHA-1``, 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`` option in the connection string. The following example instructs the
+driver to use ``users`` as the authentication database:
+
+.. code-block:: csharp
+   :copyable: true
+
+   using MongoDB.Driver;
+
+   // Connection URI
+   const string connectionUri = "mongodb://<username>:<password>@<hostname>:<port>/?authSource=users";
+
+   // Create a new client and connect to the server
+   var client = new MongoClient(connectionUri);
+
+You can also set configuration settings by creating a ``MongoClientSettings``
+object and passing that to the ``MongoClient`` constructor. You can use the
+``Credential`` property to set the login credentials including specifying the
+authentication database. For more information about using ``MongoClientSettings``
+as well as some examples, see
+:ref:`Using MongoClientSettings <csharp-mongo-client-settings>`.
+
+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 <csharp-troubleshooting-connection-firewall>` in
+the Connection Error section.
+
+.. _csharp-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 ``MaxConnectionPoolSize``
+which defines this limit. The default value is ``100``. If there are already a
+number of open connections equal to ``MaxConnectionPoolSize``, the server waits until
+a connection becomes available. If this wait time exceeds the ``MaxConnectionIdleTime``
+value, the driver responds with an error.
+
+For more information about how connection pooling works, see
+:ref:`How Does Connection Pooling Work in the {+driver-short+}? <csharp-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 ``MaxConnectionPoolSize``. For more
+information about checking the number of connections, see
+:ref:`Check the Number of Connections <csharp-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 the driver
+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.
+
+You can set this option on the connection string. The following example sets
+``connectTimeoutMS`` to 10000 milliseconds.
+
+.. code-block:: csharp
+   :copyable: true
+
+   using MongoDB.Driver;
+
+   // Connection URI
+   const string connectionUri = "mongodb://<username>:<password>@<hostname>:<port>/?connectTimeoutMS=10000";
+
+   // Create a new client and connect to the server
+   var client = new MongoClient(connectionUri);
+
+You can also set configuration settings by creating a ``MongoClientSettings``
+object and passing that to the ``MongoClient`` constructor. For more information
+about using ``MongoClientSettings`` as well as some examples, see
+:ref:`Using MongoClientSettings <csharp-mongo-client-settings>`.
+
+Check the Number of Connections
+-------------------------------
+
+The number of connections to the server may exceed ``MaxConnectionPoolSize``. For more
+information about checking the number of connections, see
+:ref:`Check the Number of Connections <csharp-troubleshooting-connection-number-connections>`
+in the Error Sending Message section.

source/faq.txt

@@ -18,6 +18,13 @@ This page contains frequently asked questions and their corresponding answers.
    see the :ref:`csharp-issues-help` page for next steps and more
    resources.
 
+Why Am I Getting Errors While Connecting to MongoDB?
+----------------------------------------------------
+
+If you have trouble connecting to a MongoDB deployment, see
+the :ref:`Connection Troubleshooting Guide <csharp-connection-troubleshooting>`
+for possible solutions.
+
 .. _csharp-faq-connection-pool:
 
 How Does Connection Pooling Work in the {+driver-short+}?
@@ -165,43 +172,6 @@ The error message consists of multiple parts:
      can use tools like ``openssl s_client`` to debug TLS/SSL-related
      certificate problems.
 
-Why is the Wait Queue for Acquiring a Connection to the Server Full?
---------------------------------------------------------------------
-
-This exception usually indicates a threading or concurrency problem in
-your application. The driver checks out a connection from the selected
-server’s connection pool for every read or write operation. If
-the connection pool is already at ``maxPoolSize`` - 100 by default - then the
-requesting thread blocks in a wait queue. The wait queue's default size
-is 5 times ``maxPoolSize``, or 500. If the wait queue is also full, the driver
-throws a ``MongoWaitQueueFullException``. The exception looks
-similar to the following:
-
-.. code-block:: none
-   
-   MongoDB.Driver.MongoWaitQueueFullException: The wait queue for
-   acquiring a connection to server myServer is full.
-
-To resolve this issue, try the following steps:
-
-1. Tune your indexes. By improving the performance of your queries,
-   you can reduce the time that operations take and reduce the number of
-   concurrent connections needed for your workload.
-#. If you have long-running analytical queries, you may wish to isolate
-   them to dedicated analytics nodes using :manual:`read preference tags
-   </core/read-preference/>` or a hidden secondary.
-#. Increase ``maxPoolSize`` to allow more simultaneous operations to a
-   given cluster node. If your MongoDB cluster does not have sufficient
-   resources to handle the additional connections and simultaneous
-   workload, performance can decrease due to resource contention
-   on the cluster nodes. Adjust this setting only with careful
-   consideration and testing.
-#. Increase ``waitQueueMultiple`` to allow more threads/tasks to block
-   waiting for a connection. This is rarely the appropriate solution and
-   can severely affect your application performance. Before
-   considering changes to this setting, address the concurrency problems
-   in your application.
-
 .. _csharp-faq-unsupported-expressions:
 
 Why are Certain LINQ or Builder Expressions Unsupported?

source/fundamentals/connection/connect.txt

@@ -15,6 +15,8 @@ Connection Guide
 This guide shows you how to connect to a MongoDB instance or replica set
 deployment using the {+driver-short+}.
 
+.. _csharp_connection_uri:
+
 Connection URI
 --------------