From 9df45a1e7cc0728035469ef8e74e6173b33673c6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 10:35:20 -0400 Subject: [PATCH 1/6] DOCSP-50185: Connection troubleshooting --- source/connect/connection-troubleshooting.txt | 166 ++++++++++++++++++ 1 file changed, 166 insertions(+) create mode 100644 source/connect/connection-troubleshooting.txt diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt new file mode 100644 index 00000000..05c456d3 --- /dev/null +++ b/source/connect/connection-troubleshooting.txt @@ -0,0 +1,166 @@ +.. _php-connection-troubleshooting: + +========================== +Connection Troubleshooting +========================== + +.. contents:: On this page + :local: + :backlinks: none + :depth: 2 + :class: singlecol + +.. facet:: + :name: genre + :values: reference + +.. meta:: + :keywords: code example, disconnected, deployment + +.. sharedinclude:: dbx/connection-troubleshooting.rst + + .. replacement:: non-connection-issue-callout + + .. note:: + + This page addresses only connection issues. If you encounter other + issues when using MongoDB or the {+library-short+}, visit the following resources: + + - The :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the libraryß, and + finding more resources + - The :community-forum:`MongoDB Community Forums ` for + questions, discussions, or general technical support + + .. replacement:: server-selection-timeout-error + + .. code-block:: none + :copyable: false + + No suitable servers found (`serverSelectionTryOnce` set): + [connection refused calling hello on 'localhost:27017'] + + .. replacement:: check-connection-string-anchor + + .. _php-connection-string-port: + + .. replacement:: multiple-hosts-connection-guide-link + + To learn how to specify multiple replica set hosts, see the + :ref:`Replica Sets ` section of the + Choose a Connection Target guide. + + .. replacement:: configure-firewall-anchor + + .. _php-connection-firewall: + + .. replacement:: authentication-error-anchor + + .. _php-authentication-error: + + .. replacement:: scram-failure-error + + .. code-block:: none + :copyable: false + + Authentication failed. + + .. replacement:: check-credentials-formatting-anchor + + .. _php-connection-string-auth: + + .. replacement:: learn-more-connection-string-admonition + + .. tip:: + + To learn more information about using connection strings, + see :ref:`Connection URI ` in the + Create a MongoDB Client guide. + + .. replacement:: percent-encode-example + + .. replacement:: verify-authentication-database-anchor + + .. _php-verify-auth-db: + + .. replacement:: authsource-param-code-block + + .. code-block:: java + :copyable: false + + $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; + $client = new MongoDB\Client($uri); + + .. replacement:: credentials-provider-alternative-method-description + + If you construct a client by using a ``MongoCredential``, the builder method + corresponds to the authentication mechanism. The following code shows the builder + method for the ``SCRAM-SHA-256`` authentication mechanism: + + .. code-block:: java + :copyable: false + + MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); + + + .. replacement:: authentication-guide-reference + + To learn more about specifying authentication mechanisms, see the :ref:`java-authentication-mechanisms` + section. + + .. replacement:: verify-authentication-mechanism-anchor + + .. _java-verify-auth-mechanism: + + .. replacement:: authsource-param-code-block + + .. code-block:: java + :copyable: false + + MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=users"); + + .. replacement:: dns-resolution-anchor + + .. _java-dns-resolution-error: + + .. replacement:: dns-error-message + + .. code-block:: none + :copyable: false + + com.mongodb.MongoSocketWriteException: Exception sending message + + .. replacement:: check-the-number-of-connections-anchor + + .. _java-connection-num-connections: + + .. replacement:: mongo-client-class + + ``MongoClient`` + + .. replacement:: max-pool-size-param + + ``maxPoolSize`` + + .. replacement:: max-pool-size-default + + ``100`` + + .. replacement:: max-idle-time-param + + ``maxIdleTimeMS`` + + .. replacement:: scram-failure-error + + .. code-block:: + + Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + + .. replacement:: check-credentials-formatting-anchor + + .. _java-troubleshooting-connection-string-auth: + + .. replacement:: connection-pools-learn-more + + To learn more about how connection pooling works in the driver, see the + :ref:`Connection Pools ` page. \ No newline at end of file From 5f7d096ce02624a232ba4c5e5013f968dfcf6e6d Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 16:01:08 -0400 Subject: [PATCH 2/6] edits --- source/connect.txt | 2 - source/connect/connection-options.txt | 2 +- source/connect/connection-troubleshooting.txt | 44 +++++++++++-------- 3 files changed, 27 insertions(+), 21 deletions(-) diff --git a/source/connect.txt b/source/connect.txt index 6db0b4fe..8ce1b09c 100644 --- a/source/connect.txt +++ b/source/connect.txt @@ -26,8 +26,6 @@ Connect to MongoDB Choose a Connection Target Connection Options Connect with AWS Lambda - -.. TODO: Connection Troubleshooting Overview diff --git a/source/connect/connection-options.txt b/source/connect/connection-options.txt index 054becb2..d50932ee 100644 --- a/source/connect/connection-options.txt +++ b/source/connect/connection-options.txt @@ -34,7 +34,7 @@ Set Connection Options You can configure your connection by specifying options in the connection URI or by passing them to the ``MongoDB\Client`` constructor. -.. _php-connection-uri: +.. _php-connection-options-uri: Using the Connection URI ~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 05c456d3..c170f923 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -93,31 +93,42 @@ Connection Troubleshooting .. replacement:: credentials-provider-alternative-method-description - If you construct a client by using a ``MongoCredential``, the builder method - corresponds to the authentication mechanism. The following code shows the builder - method for the ``SCRAM-SHA-256`` authentication mechanism: + If you use the ``$uriOptions`` parameter to specify an authentication mechanism, + ensure that you set the ``'authMechanism'`` option to the correct mechanism. The + following code shows how to specify the ``SCRAM-SHA-1`` authentication mechanism + in an options parameter: - .. code-block:: java + .. code-block:: php :copyable: false - MongoCredential credential = MongoCredential.createScramSha256Credential("", "", ""); + $uriOptions = [ + 'username' => '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-1', + ]; + $client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, + ); .. replacement:: authentication-guide-reference - To learn more about specifying authentication mechanisms, see the :ref:`java-authentication-mechanisms` + To learn more about specifying authentication mechanisms, see the :ref:`php-auth` section. .. replacement:: verify-authentication-mechanism-anchor - .. _java-verify-auth-mechanism: + .. _php-verify-auth-mechanism: .. replacement:: authsource-param-code-block - .. code-block:: java + .. code-block:: php :copyable: false - MongoClient mongoClient = MongoClients.create("mongodb://:@:/?authSource=users"); + $uri = 'mongodb://:@:/?authSource=users'; + $client = new MongoDB\Client($uri); .. replacement:: dns-resolution-anchor @@ -128,15 +139,15 @@ Connection Troubleshooting .. code-block:: none :copyable: false - com.mongodb.MongoSocketWriteException: Exception sending message + No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '']. .. replacement:: check-the-number-of-connections-anchor - .. _java-connection-num-connections: + .. _php-connection-num-connections: .. replacement:: mongo-client-class - ``MongoClient`` + ``MongoDB\Client`` .. replacement:: max-pool-size-param @@ -154,13 +165,10 @@ Connection Troubleshooting .. code-block:: - Command failed with error 18 (AuthenticationFailed): 'Authentication failed.' on server localhost:27017. + Authentication failed. .. replacement:: check-credentials-formatting-anchor - .. _java-troubleshooting-connection-string-auth: - - .. replacement:: connection-pools-learn-more + .. _php-troubleshooting-connection-string-auth: - To learn more about how connection pooling works in the driver, see the - :ref:`Connection Pools ` page. \ No newline at end of file + .. replacement:: connection-pools-learn-more \ No newline at end of file From 590dc587fa92e52aae4c57394b07eb620a8e735e Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 16:14:39 -0400 Subject: [PATCH 3/6] remove sharedinclude --- source/connect/connection-troubleshooting.txt | 230 ++++++++++-------- 1 file changed, 131 insertions(+), 99 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index c170f923..4298b33e 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -17,158 +17,190 @@ Connection Troubleshooting .. meta:: :keywords: code example, disconnected, deployment -.. sharedinclude:: dbx/connection-troubleshooting.rst +This page offers potential solutions to issues that you might encounter +when using the {+library-short+} to connect to a MongoDB deployment. - .. replacement:: non-connection-issue-callout +.. note:: - .. note:: + This page addresses only connection issues. If you encounter other + issues when using MongoDB or the {+library-short+}, visit the following resources: - This page addresses only connection issues. If you encounter other - issues when using MongoDB or the {+library-short+}, visit the following resources: + - The :ref:`Issues & Help ` page for + information about reporting bugs, contributing to the libraryß, and + finding more resources + - The :community-forum:`MongoDB Community Forums ` for + questions, discussions, or general technical support - - The :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the libraryß, and - finding more resources - - The :community-forum:`MongoDB Community Forums ` for - questions, discussions, or general technical support +Server Connection Errors +------------------------ - .. replacement:: server-selection-timeout-error +When an issue occurs when you attempt to connect to a server, the {+driver-short+} +returns an error message. If this error resembles the following message, it +indicates that the driver cannot connect to a MongoDB deployment: - .. code-block:: none - :copyable: false +.. code-block:: none + :copyable: false - No suitable servers found (`serverSelectionTryOnce` set): - [connection refused calling hello on 'localhost:27017'] + No suitable servers found (`serverSelectionTryOnce` set): + [connection refused calling hello on 'localhost:27017'] - .. replacement:: check-connection-string-anchor +The following sections describe methods that might help resolve the issue. - .. _php-connection-string-port: +Check the Connection String +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. replacement:: multiple-hosts-connection-guide-link +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 an instance of MongoDB Server is +``27017``, but you can configure MongoDB to listen on another port. - To learn how to specify multiple replica set hosts, see the - :ref:`Replica Sets ` section of the - Choose a Connection Target guide. +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. - .. replacement:: configure-firewall-anchor +To learn how to specify multiple replica set hosts, see the +:ref:`Replica Sets ` section of the +Choose a Connection Target guide. - .. _php-connection-firewall: +Configure the Firewall +~~~~~~~~~~~~~~~~~~~~~~ - .. replacement:: authentication-error-anchor +If your MongoDB deployment is hosted behind a firewall, ensure the port +on which MongoDB listens is open in the firewall. If your deployment +listens on the default network port, ensure that port ``27017`` is +open in the firewall. If your deployment listens on a different port, +ensure that port is open on the firewall. - .. _php-authentication-error: +.. warning:: - .. replacement:: scram-failure-error + Do not open a firewall port unless you are sure that it is the one + that your MongoDB deployment listens on. - .. code-block:: none - :copyable: false +Authentication Errors +--------------------- - Authentication failed. +The {+driver-short+} may be unable connect to a MongoDB deployment if +the authorization is not configured correctly. In these cases, the driver +raises an error message similar to the following message: - .. replacement:: check-credentials-formatting-anchor +.. code-block:: none + :copyable: false - .. _php-connection-string-auth: + Authentication failed. - .. replacement:: learn-more-connection-string-admonition +The following sections describe methods that may help resolve the issue. - .. tip:: +Check the Credentials Formatting +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - To learn more information about using connection strings, - see :ref:`Connection URI ` in the - Create a MongoDB Client guide. +One of the most common causes of authentication issues is invalid +credentials formatting in the MongoDB connection string. - .. replacement:: percent-encode-example +.. tip:: - .. replacement:: verify-authentication-database-anchor + To learn more information about using connection strings, + see :ref:`Connection URI ` in the + Create a MongoDB Client guide. - .. _php-verify-auth-db: +If your connection string contains a username and password, ensure that +they are correctly formatted. - .. replacement:: authsource-param-code-block +.. note:: - .. code-block:: java - :copyable: false + If your username or password includes any of the following characters, you + must `percent-encode `__ it: - $uri = 'mongodb://:@:/?authSource=admin&authMechanism=SCRAM-SHA-256'; - $client = new MongoDB\Client($uri); + .. code-block:: none + :copyable: false - .. replacement:: credentials-provider-alternative-method-description + : / ? # [ ] @ - If you use the ``$uriOptions`` parameter to specify an authentication mechanism, - ensure that you set the ``'authMechanism'`` option to the correct mechanism. The - following code shows how to specify the ``SCRAM-SHA-1`` authentication mechanism - in an options parameter: + Use your percent-encoded username and password in your connection string. - .. code-block:: php - :copyable: false +Verify the Authentication Mechanism +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - $uriOptions = [ - 'username' => '', - 'password' => '', - 'authSource' => '', - 'authMechanism' => 'SCRAM-SHA-1', - ]; +Ensure that your credentials and authentication mechanism are correct. You can +specify your authentication credentials in the options of your connection string. - $client = new MongoDB\Client( - 'mongodb://:', - $uriOptions, - ); +If you use the ``$uriOptions`` parameter to specify an authentication mechanism, +ensure that you set the ``'authMechanism'`` option to the correct mechanism. The +following code shows how to specify the ``SCRAM-SHA-1`` authentication mechanism +in an options parameter: - .. replacement:: authentication-guide-reference +.. code-block:: php + :copyable: false - To learn more about specifying authentication mechanisms, see the :ref:`php-auth` - section. + $uriOptions = [ + 'username' => '', + 'password' => '', + 'authSource' => '', + 'authMechanism' => 'SCRAM-SHA-1', + ]; - .. replacement:: verify-authentication-mechanism-anchor + $client = new MongoDB\Client( + 'mongodb://:', + $uriOptions, + ); - .. _php-verify-auth-mechanism: +To learn more about specifying authentication mechanisms, see the :ref:`php-auth` +section. - .. replacement:: authsource-param-code-block +Verify User Is in Authentication Database +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. code-block:: php - :copyable: false +When using a username and password-based authentication method, +the username must be defined in the authentication database. - $uri = 'mongodb://:@:/?authSource=users'; - $client = new MongoDB\Client($uri); +The default authentication database is the ``admin`` database. +To use a different database for authentication, specify the +``authSource`` option in the connection string. - .. replacement:: dns-resolution-anchor +The following example instructs MongoDB to use the ``users`` database +as the authentication database: - .. _java-dns-resolution-error: +.. code-block:: php + :copyable: false - .. replacement:: dns-error-message + $uri = 'mongodb://:@:/?authSource=users'; + $client = new MongoDB\Client($uri); - .. code-block:: none - :copyable: false +DNS Resolution Errors +--------------------- - No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '']. +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: - .. replacement:: check-the-number-of-connections-anchor +.. code-block:: none + :copyable: false - .. _php-connection-num-connections: + No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '']. - .. replacement:: mongo-client-class +If the driver reports this error, try the methods in the following sections +to resolve the issue. - ``MongoDB\Client`` +Check Database Deployment Availability +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. replacement:: max-pool-size-param +If you are connecting to MongoDB Atlas and your driver cannot find the DNS +host of the Atlas database deployment, the database deployment might be paused +or deleted. - ``maxPoolSize`` +Ensure that the database deployment exists in Atlas. If the cluster is paused, +you can resume the cluster in the Atlas UI or the +:atlas:`Atlas command line interface `. - .. replacement:: max-pool-size-default +To learn how to resume a cluster, see +:atlas:`Resume One Cluster ` +in the Atlas documentation. - ``100`` +Check the Network Addresses +~~~~~~~~~~~~~~~~~~~~~~~~~~~ - .. replacement:: max-idle-time-param +Verify that the network addresses or hostnames in your connection string +are accurate. - ``maxIdleTimeMS`` - - .. replacement:: scram-failure-error - - .. code-block:: - - Authentication failed. - - .. replacement:: check-credentials-formatting-anchor - - .. _php-troubleshooting-connection-string-auth: - - .. replacement:: connection-pools-learn-more \ No newline at end of file +If your deployment is hosted on MongoDB Atlas, you can follow the +:atlas:`Connect to Your Cluster ` +tutorial to find your Atlas connection string. \ No newline at end of file From 19ded8be839cf65d9619baa89a63a24d785831d6 Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 16:20:21 -0400 Subject: [PATCH 4/6] fix --- source/connect/connection-troubleshooting.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 4298b33e..ca0c9f56 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -26,10 +26,10 @@ when using the {+library-short+} to connect to a MongoDB deployment. issues when using MongoDB or the {+library-short+}, visit the following resources: - The :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the libraryß, and - finding more resources + information about reporting bugs, contributing to the libraryß, and + finding more resources - The :community-forum:`MongoDB Community Forums ` for - questions, discussions, or general technical support + questions, discussions, or general technical support Server Connection Errors ------------------------ From c71b622137a9a99cfcddc5310a68a1973277d9cb Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 16:21:20 -0400 Subject: [PATCH 5/6] wording --- source/connect/connection-troubleshooting.txt | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index ca0c9f56..573bcfc6 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -36,7 +36,7 @@ Server Connection Errors When an issue occurs when you attempt to connect to a server, the {+driver-short+} returns an error message. If this error resembles the following message, it -indicates that the driver cannot connect to a MongoDB deployment: +indicates that the library cannot connect to a MongoDB deployment: .. code-block:: none :copyable: false @@ -56,7 +56,7 @@ port is ``27017``. The default port value for an instance of MongoDB Server is 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 +string with a comma. This enables the library to establish a connection if one of the hosts is unreachable. To learn how to specify multiple replica set hosts, see the @@ -81,7 +81,7 @@ Authentication Errors --------------------- The {+driver-short+} may be unable connect to a MongoDB deployment if -the authorization is not configured correctly. In these cases, the driver +the authorization is not configured correctly. In these cases, the library raises an error message similar to the following message: .. code-block:: none @@ -177,7 +177,7 @@ happens, you might receive an error message similar to the following message: No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '']. -If the driver reports this error, try the methods in the following sections +If the library reports this error, try the methods in the following sections to resolve the issue. Check Database Deployment Availability From 2f076f559c331e8faad893d12db63e0d346d046c Mon Sep 17 00:00:00 2001 From: norareidy Date: Mon, 16 Jun 2025 16:25:13 -0400 Subject: [PATCH 6/6] fix --- source/connect/connection-troubleshooting.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/connect/connection-troubleshooting.txt b/source/connect/connection-troubleshooting.txt index 573bcfc6..44aebfa8 100644 --- a/source/connect/connection-troubleshooting.txt +++ b/source/connect/connection-troubleshooting.txt @@ -26,7 +26,7 @@ when using the {+library-short+} to connect to a MongoDB deployment. issues when using MongoDB or the {+library-short+}, visit the following resources: - The :ref:`Issues & Help ` page for - information about reporting bugs, contributing to the libraryß, and + information about reporting bugs, contributing to the library, and finding more resources - The :community-forum:`MongoDB Community Forums ` for questions, discussions, or general technical support