Merge pull request #260 from DBirtolo-mdb/DOCSP-29489

DBirtolo-mdb · web-flow · commit 5be5839fd27a · 2023-05-15T14:29:46.000-07:00
Added Connection Troubleshooting guide
diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt
@@ -0,0 +1,241 @@
+.. _golang-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) <golang-faq>` for the
+     {+driver-short+}
+   - The :ref:`Issues & Help <golang-issues-and-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:
+
+.. code-block:: none
+   :copyable: false
+
+   Error: couldn't connect to server 127.0.0.1:27017
+
+The following sections describe methods that may help resolve the issue.
+
+.. _golang-troubleshooting-connection-string-port:
+
+Check Connection String
+-----------------------
+
+Verify that the hostname and port number in the connection string are both
+accurate. In the sample error message, the hostname is ``127.0.0.1`` and the
+port is ``27017``. The default port value for a MongoDB instance is
+``27017``, but you can configure MongoDB to communicate on another port.
+
+.. _golang-troubleshooting-connection-firewall:
+
+Configure Firewall
+------------------
+
+Assuming that your MongoDB deployment uses the default port, verify that port
+``27017`` is open in your firewall. If your deployment uses a different port,
+verify the correct port is open in your firewall.
+
+.. warning::
+
+   Do not open a port in your firewall unless you are sure that it is the port
+   used by your MongoDB instance.
+
+Authentication Error
+~~~~~~~~~~~~~~~~~~~~
+
+The {+driver-short+} can fail to connect to a MongoDB instance if
+the authorization is not configured correctly. In these cases, the driver raises
+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 localhost:27017.
+
+.. 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 methods that may help resolve the issue.
+
+.. _golang-troubleshooting-connection-string-auth:
+
+Check Connection String
+-----------------------
+
+An invalid connection string is the most common cause of authentication
+issues when attempting to connect to MongoDB.
+
+.. tip::
+
+   For more information about connection strings,
+   see :ref:`Connection URI <golang-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
+
+      : / ? # [ ] @
+
+When connecting to a replica set, you should include all of the hosts
+in the replica set in your connection string. Separate each of the hosts
+in the connection string with a comma. This enables the driver to establish a
+connection if one of the hosts is unreachable.
+
+.. _golang-troubleshooting-connection-auth-mechanism:
+
+Verify the Authentication Mechanism
+-----------------------------------
+
+Ensure that your credentials and authentication mechanism are correct. You can
+store your authentication credentials in environment variables or you can pass
+them to the ``SetAuth()`` method.
+
+To learn more about authentication, see the
+:ref:`golang-authentication-mechanisms` guide.
+
+.. _golang-troubleshooting-connection-admin:
+
+Verify User Is in Authentication Database
+-----------------------------------------
+
+To successfully authenticate a connection by using a username and password,
+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:: go
+   :copyable: true
+
+   uri := "mongodb://<username>:<password>@<hostname>:<port>/?authSource=users"
+   client := mongo.Connect(uri)
+
+Error Sending Message
+~~~~~~~~~~~~~~~~~~~~~
+
+When the driver fails to send a command after you make a request,
+it often displays the following general error message:
+
+.. code-block:: none
+   :copyable: false
+
+   com.mongodb.MongoSocketWriteException: Exception sending message
+
+The following sections describe methods that may help resolve the issue.
+
+Check Connection String
+-----------------------
+
+Verify that the connection string in your app is accurate. For more information
+about verifying your connection string, see
+:ref:`Connection Error <golang-troubleshooting-connection-string-port>`
+and :ref:`Authentication Error <golang-troubleshooting-connection-string-auth>`.
+
+Verify the Authentication Mechanism
+-----------------------------------
+
+Make sure you are using the correct authentication mechanism and credentials.
+For more information about authentication errors, see
+:ref:`Authentication Error <golang-troubleshooting-connection-auth-mechanism>`.
+
+Verify User Is in Authentication Database
+-----------------------------------------
+
+Verify the user is in the correct authentication database. For more
+information about the authentication database, see
+:ref:`Authentication Error <golang-troubleshooting-connection-admin>`.
+
+Configure 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 <golang-troubleshooting-connection-firewall>`.
+
+.. _golang-troubleshooting-connection-number-connections:
+
+Check the Number of Connections
+-------------------------------
+
+Each ``MongoClient`` instance supports a maximum number of concurrent open
+connections in its connection pool. The configuration parameter ``maxPoolSize``
+defines this value and is set to ``100`` by default. 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 Go Driver? <golang-faq-connection-pool>`
+in the FAQ.
+
+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 methods to resolve the
+issue.
+
+Set Timeout Option
+------------------
+
+The ``Client`` supports a single ``Timeout`` option that controls the amount of
+time a single operation can take to execute. You can set this value by using
+the ``SetTimeout()`` method or by specifying the ``timeoutMS`` option in your
+connection string. 
+
+The following example sets the single timeout value to 5 seconds using the
+connection string option:
+
+.. code-block:: go
+
+   uri := "mongodb://<username>:<password>@<hostname>:27017/?timeoutMS=5000"
+   client := mongo.Connect(uri)
+
+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 <golang-troubleshooting-connection-number-connections>`.
diff --git a/source/faq.txt b/source/faq.txt
@@ -20,6 +20,13 @@ This page contains frequently asked questions and their corresponding answers.
    see the :ref:`golang-issues-and-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 <golang-connection-troubleshooting>`
+for possible solutions.
+
 .. _golang-faq-connection-pool:
 
 How Does Connection Pooling Work in the {+driver-short+}?
@@ -177,35 +184,3 @@ using string type-casting:
 
 To learn more about conversions between BSON and Go types, see the
 :ref:`golang-bson` guide.
-
-Why Did the Driver Throw an "Authentication failed" Error?
-----------------------------------------------------------
-
-If you attempt to connect to a MongoDB deployment using incorrect
-username and password credentials or specifying the wrong authentication
-mechanism, you receive an "Authentication failed" error message. For
-example, the following error message is returned when you pass invalid
-credentials when authenticating with ``SCRAM-SHA-256``:
-
-.. 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.
-
-This error message does not contain the detailed authentication failure
-reason for security reasons. Common causes for authentication failure include the
-following:
-
-- Incorrect password
-- Incorrect username
-- Incorrect authentication mechanism specified in your connection string
-  or ``Credential`` struct
-
-To avoid this error, ensure that your credentials and authentication
-mechanism are correct. You can store your authentication credentials in
-environment variables or you can pass them to the ``SetAuth()`` method.
-
-To learn more about authentication, see the
-:ref:`golang-authentication-mechanisms` guide.
diff --git a/source/fundamentals/connection.txt b/source/fundamentals/connection.txt
@@ -15,6 +15,8 @@ Connection Guide
 This guide shows you how to connect to a MongoDB instance or replica set
 deployment using the Go Driver.
 
+.. _golang-connection-uri:
+
 --------------
 Connection URI
 --------------
diff --git a/source/index.txt b/source/index.txt
@@ -15,6 +15,7 @@
    /fundamentals
    API Documentation <{+api+}/mongo>
    /faq
+   /connection-troubleshooting
    /issues-and-help
    /compatibility
    View the Source <https://github.com/mongodb/mongo-go-driver>
@@ -73,6 +74,13 @@ For answers to commonly asked questions about the MongoDB
 Go Driver, see :ref:`golang-faq`
 section.
 
+Connection Troubleshooting
+--------------------------
+
+For solutions to some issues you might see when connecting to a MongoDB
+deployment while using the {+driver-long+}, see
+:ref:`golang-connection-troubleshooting`.
+
 Issues & Help
 -------------
 
