connection-troubleshooting.txt

.. _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>`.