diff --git a/source/connection-troubleshooting.txt b/source/connection-troubleshooting.txt index a1e70717..7a2d2a3e 100644 --- a/source/connection-troubleshooting.txt +++ b/source/connection-troubleshooting.txt @@ -10,198 +10,143 @@ Connection Troubleshooting :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. +.. facet:: + :name: genre + :values: reference -.. note:: +.. meta:: + :keyworrds: code example, disconnected, deployment - This page only addresses connection issues. If you encounter any other issues - with MongoDB or the driver, visit the following resources: +.. sharedinclude:: dbx/connection-troubleshooting.rst - - :ref:`rust-operation-errors` for recommendations on how to handle - different error types that the driver raises during operations - - :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the driver, and - finding more resources - - `MongoDB Community Forums `__ for - questions, discussions, or general technical support - - .. - TODO: - - The :ref:`Frequently Asked Questions (FAQ) ` for the - {+driver-short+} + .. replacement:: non-connection-issue-callout -Server Connection Error -~~~~~~~~~~~~~~~~~~~~~~~ + .. note:: -When you attempt to connect to a server, the {+driver-short+} might generate an -error message. This message might look similar to the following message indicating -that the driver cannot connect to a server on the specified hostname or port: + This page only addresses connection issues. If you encounter any other issues + with MongoDB or the driver, visit the following resources: -.. code-block:: none - :copyable: false + - :ref:`rust-operation-errors` for recommendations on how to handle + different error types that the driver raises during operations + - :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the driver, and + finding more resources + - `MongoDB Community Forums `__ for + questions, discussions, or general technical support + - The :ref:`Frequently Asked Questions (FAQ) ` section for + common questions and corresponding answers about the + {+driver-short+} - Error: Error { kind: ServerSelection { message: "Server selection timeout: - No available servers. Topology: { Type: Unknown, Servers: [ { Address: - 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused - (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: - None } + .. replacement:: server-selection-timeout-error -The following sections describe methods that might help resolve the issue. + .. code-block:: none + :copyable: false -.. _rust-troubleshooting-connection-string-port: + Error: Error { kind: ServerSelection { message: "Server selection timeout: + No available servers. Topology: { Type: Unknown, Servers: [ { Address: + 127.0.0.1:27017, Type: Unknown, Error: Kind: I/O error: Connection refused + (os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source: + None } -Check Connection String ------------------------ + .. replacement:: check-connection-string-anchor -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. + .. _rust-troubleshooting-connection-string-port: -.. _rust-troubleshooting-connection-firewall: + .. replacement:: multiple-hosts-connection-guide-link -Configure Firewall ------------------- + To learn more about specifying multiple hosts in a replica set, see the + :ref:`Connect to a Replica Set ` section of the + Connection Guide. -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. + .. replacement:: configure-firewall-anchor -.. warning:: + .. _rust-troubleshooting-connection-firewall: - Do not open a port in your firewall unless you are sure that it is the port - used by your MongoDB instance. + .. replacement:: check-the-number-of-connections-anchor -.. _rust-troubleshooting-connection-number-connections: + .. _rust-troubleshooting-connection-number-connections: -Check the Number of Connections -------------------------------- + .. replacement:: mongo-client-class -Each ``Client`` 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. + ``Client`` -.. - TODO To learn more about how connection pools work in the driver, see - the :ref:`FAQ page `. + .. replacement:: max-pool-size-param -Authentication Error -~~~~~~~~~~~~~~~~~~~~ + ``maxPoolSize`` -The {+driver-short+} may be unable connect to a MongoDB instance if -the authorization is not configured correctly. In these cases, the driver -raises an error message similar to the following message: + .. replacement:: max-pool-size-default -.. code-block:: none - :copyable: false + ``100`` - Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : - authentication failed" }, labels: {}, wire_version: None, source: Some(Error - { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: - "bad auth : authentication failed", topology_version: None }), - labels: {}, wire_version: None, source: None }) } + .. replacement:: max-idle-time-param -The following sections describe methods that may help resolve the issue. + ``maxIdleTimeMS`` -.. _rust-troubleshooting-connection-string-auth: + .. replacement:: connection-pools-learn-more -Check Connection String ------------------------ + To learn more about how connection pools work in the driver, see + :ref:`How Does Connection Pooling Work in the Rust Driver? ` + on the FAQ page. -An invalid connection string is the most common cause of authentication -issues when attempting to connect to MongoDB. + .. replacement:: authentication-error-anchor -.. tip:: + .. _rust-troubleshooting-auth-error: - For more information about connection strings, - see the :ref:`rust-quick-start-connection-string` guide. + .. replacement:: scram-failure-error -If your connection string contains a username and password, ensure that they -are in the correct format. + .. code-block:: none + :copyable: false -.. note:: + Error: Error { kind: Authentication { message: "SCRAM failure: bad auth : + authentication failed" }, labels: {}, wire_version: None, source: Some(Error + { kind: Command(CommandError { code: 8000, code_name: "AtlasError", message: + "bad auth : authentication failed", topology_version: None }), + labels: {}, wire_version: None, source: None }) } - If your username or password includes any of the following characters, you - must `percent encode `__ it: + .. replacement:: check-credentials-formatting-anchor - .. code-block:: none - :copyable: false + .. _rust-troubleshooting-connection-string-auth: - : / ? # [ ] @ - - After percent encoding your username and password, you can use them as - credentials in your connection string. + .. replacement:: learn-more-connection-string-admonition -When connecting to a replica set, include all the replica set hosts 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. For an example of a connection string -that specifies multiple replica set hosts, see :ref:`Connect to a Replica Set -` in the Connection Guide. + .. tip:: -.. _rust-troubleshooting-connection-auth-mechanism: + For more information about connection strings, + see the :ref:`rust-quick-start-connection-string` guide. -Verify the Authentication Mechanism ------------------------------------ + .. replacement:: verify-authentication-mechanism-anchor -Ensure that your credentials and authentication mechanism are correct. You can -specify your authentication credentials in the options of your connection string -or in a ``Credential`` struct. + .. _rust-troubleshooting-connection-auth-mechanism: -To learn more about authentication, see the -:ref:`rust-authentication` guide. + .. replacement:: credentials-provider-alternative-method-description -.. _rust-troubleshooting-connection-admin: + Alternatively, you can specify your authentication credentials in a + ``Credential`` struct. -Verify User Is in Authentication Database ------------------------------------------ + .. replacement:: authentication-guide-reference -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`` option in the connection string. -The following example instructs the driver to use ``users`` as the authentication -database: + To learn more about authentication, see the :ref:`rust-authentication` guide. -.. code-block:: rust - :copyable: true + .. replacement:: verify-authentication-database-anchor - let uri = "mongodb://:@:/?authSource=users"; - let client = Client::with_uri_str(uri).await?; + .. _rust-troubleshooting-connection-admin: -DNS Resolution Error -~~~~~~~~~~~~~~~~~~~~ + .. replacement:: authsource-param-code-block -The {+driver-short+} may be unable to resolve your DNS connection. When this -happens, you might receive an error message similar to the following message: + .. code-block:: rust + :copyable: true -.. code-block:: none - :copyable: false + let uri = "mongodb://:@:/?authSource=users"; + let client = Client::with_uri_str(uri).await?; - Error: Error { kind: DnsResolve { message: "sample message. type: - SRV class: IN" }, labels: {}, wire_version: None, source: None } + .. replacement:: dns-resolution-anchor -If you receive this error, try the following methods to resolve the issue. + .. _rust-troubleshooting-connection-dns-resolution: -Check Database Deployment Availability --------------------------------------- + .. replacement:: dns-error-message -If you are using an Atlas connection string and your driver cannot find the DNS host -of the Atlas database deployment, the database deployment might be paused or deleted. -Check that the database deployment exists. If the cluster is paused, you can resume -the cluster on the Atlas UI or the Atlas command line interface. + .. code-block:: none + :copyable: false -To learn how to resume a cluster, see :atlas:`Resume One Cluster -` in the Atlas documentation. - -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 ` -and :ref:`Authentication Error `. + Error: Error { kind: DnsResolve { message: "sample message. type: + SRV class: IN" }, labels: {}, wire_version: None, source: None }