Skip to content

Commit 590dc58

Browse files
norareidynorareidy
committed
remove sharedinclude
1 parent 5f7d096 commit 590dc58

File tree

1 file changed

+131
-99
lines changed

1 file changed

+131
-99
lines changed

‎source/connect/connection-troubleshooting.txt‎

Lines changed: 131 additions & 99 deletions
Original file line numberDiff line numberDiff line change
@@ -17,158 +17,190 @@ Connection Troubleshooting
1717
.. meta::
1818
:keywords: code example, disconnected, deployment
1919

20-
.. sharedinclude:: dbx/connection-troubleshooting.rst
20+
This page offers potential solutions to issues that you might encounter
21+
when using the {+library-short+} to connect to a MongoDB deployment.
2122

22-
.. replacement:: non-connection-issue-callout
23+
.. note::
2324

24-
.. note::
25+
This page addresses only connection issues. If you encounter other
26+
issues when using MongoDB or the {+library-short+}, visit the following resources:
2527

26-
This page addresses only connection issues. If you encounter other
27-
issues when using MongoDB or the {+library-short+}, visit the following resources:
28+
- The :ref:`Issues & Help <php-issues-and-help>` page for
29+
information about reporting bugs, contributing to the libraryß, and
30+
finding more resources
31+
- The :community-forum:`MongoDB Community Forums </tag/php>` for
32+
questions, discussions, or general technical support
2833

29-
- The :ref:`Issues & Help <php-issues-and-help>` page for
30-
information about reporting bugs, contributing to the libraryß, and
31-
finding more resources
32-
- The :community-forum:`MongoDB Community Forums </tag/php>` for
33-
questions, discussions, or general technical support
34+
Server Connection Errors
35+
------------------------
3436

35-
.. replacement:: server-selection-timeout-error
37+
When an issue occurs when you attempt to connect to a server, the {+driver-short+}
38+
returns an error message. If this error resembles the following message, it
39+
indicates that the driver cannot connect to a MongoDB deployment:
3640

37-
.. code-block:: none
38-
:copyable: false
41+
.. code-block:: none
42+
:copyable: false
3943

40-
No suitable servers found (`serverSelectionTryOnce` set):
41-
[connection refused calling hello on 'localhost:27017']
44+
No suitable servers found (`serverSelectionTryOnce` set):
45+
[connection refused calling hello on 'localhost:27017']
4246

43-
.. replacement:: check-connection-string-anchor
47+
The following sections describe methods that might help resolve the issue.
4448

45-
.. _php-connection-string-port:
49+
Check the Connection String
50+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
4651

47-
.. replacement:: multiple-hosts-connection-guide-link
52+
Verify that the hostname and port number in the connection string are both
53+
accurate. In the sample error message, the hostname is ``127.0.0.1`` and the
54+
port is ``27017``. The default port value for an instance of MongoDB Server is
55+
``27017``, but you can configure MongoDB to listen on another port.
4856

49-
To learn how to specify multiple replica set hosts, see the
50-
:ref:`Replica Sets <php-connection-replica-set>` section of the
51-
Choose a Connection Target guide.
57+
When connecting to a replica set, include all the replica set hosts in
58+
your connection string. Separate each of the hosts in the connection
59+
string with a comma. This enables the driver to establish a connection if
60+
one of the hosts is unreachable.
5261

53-
.. replacement:: configure-firewall-anchor
62+
To learn how to specify multiple replica set hosts, see the
63+
:ref:`Replica Sets <php-connection-replica-set>` section of the
64+
Choose a Connection Target guide.
5465

55-
.. _php-connection-firewall:
66+
Configure the Firewall
67+
~~~~~~~~~~~~~~~~~~~~~~
5668

57-
.. replacement:: authentication-error-anchor
69+
If your MongoDB deployment is hosted behind a firewall, ensure the port
70+
on which MongoDB listens is open in the firewall. If your deployment
71+
listens on the default network port, ensure that port ``27017`` is
72+
open in the firewall. If your deployment listens on a different port,
73+
ensure that port is open on the firewall.
5874

59-
.. _php-authentication-error:
75+
.. warning::
6076

61-
.. replacement:: scram-failure-error
77+
Do not open a firewall port unless you are sure that it is the one
78+
that your MongoDB deployment listens on.
6279

63-
.. code-block:: none
64-
:copyable: false
80+
Authentication Errors
81+
---------------------
6582

66-
Authentication failed.
83+
The {+driver-short+} may be unable connect to a MongoDB deployment if
84+
the authorization is not configured correctly. In these cases, the driver
85+
raises an error message similar to the following message:
6786

68-
.. replacement:: check-credentials-formatting-anchor
87+
.. code-block:: none
88+
:copyable: false
6989

70-
.. _php-connection-string-auth:
90+
Authentication failed.
7191

72-
.. replacement:: learn-more-connection-string-admonition
92+
The following sections describe methods that may help resolve the issue.
7393

74-
.. tip::
94+
Check the Credentials Formatting
95+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7596

76-
To learn more information about using connection strings,
77-
see :ref:`Connection URI <php-connection-uri>` in the
78-
Create a MongoDB Client guide.
97+
One of the most common causes of authentication issues is invalid
98+
credentials formatting in the MongoDB connection string.
7999

80-
.. replacement:: percent-encode-example
100+
.. tip::
81101

82-
.. replacement:: verify-authentication-database-anchor
102+
To learn more information about using connection strings,
103+
see :ref:`Connection URI <php-connection-uri>` in the
104+
Create a MongoDB Client guide.
83105

84-
.. _php-verify-auth-db:
106+
If your connection string contains a username and password, ensure that
107+
they are correctly formatted.
85108

86-
.. replacement:: authsource-param-code-block
109+
.. note::
87110

88-
.. code-block:: java
89-
:copyable: false
111+
If your username or password includes any of the following characters, you
112+
must `percent-encode <https://tools.ietf.org/html/rfc3986#section-2.1>`__ it:
90113

91-
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=admin&authMechanism=SCRAM-SHA-256';
92-
$client = new MongoDB\Client($uri);
114+
.. code-block:: none
115+
:copyable: false
93116

94-
.. replacement:: credentials-provider-alternative-method-description
117+
: / ? # [ ] @
95118

96-
If you use the ``$uriOptions`` parameter to specify an authentication mechanism,
97-
ensure that you set the ``'authMechanism'`` option to the correct mechanism. The
98-
following code shows how to specify the ``SCRAM-SHA-1`` authentication mechanism
99-
in an options parameter:
119+
Use your percent-encoded username and password in your connection string.
100120

101-
.. code-block:: php
102-
:copyable: false
121+
Verify the Authentication Mechanism
122+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
103123

104-
$uriOptions = [
105-
'username' => '<username>',
106-
'password' => '<password>',
107-
'authSource' => '<authentication database>',
108-
'authMechanism' => 'SCRAM-SHA-1',
109-
];
124+
Ensure that your credentials and authentication mechanism are correct. You can
125+
specify your authentication credentials in the options of your connection string.
110126

111-
$client = new MongoDB\Client(
112-
'mongodb://<hostname>:<port>',
113-
$uriOptions,
114-
);
127+
If you use the ``$uriOptions`` parameter to specify an authentication mechanism,
128+
ensure that you set the ``'authMechanism'`` option to the correct mechanism. The
129+
following code shows how to specify the ``SCRAM-SHA-1`` authentication mechanism
130+
in an options parameter:
115131

116-
.. replacement:: authentication-guide-reference
132+
.. code-block:: php
133+
:copyable: false
117134

118-
To learn more about specifying authentication mechanisms, see the :ref:`php-auth`
119-
section.
135+
$uriOptions = [
136+
'username' => '<username>',
137+
'password' => '<password>',
138+
'authSource' => '<authentication database>',
139+
'authMechanism' => 'SCRAM-SHA-1',
140+
];
120141

121-
.. replacement:: verify-authentication-mechanism-anchor
142+
$client = new MongoDB\Client(
143+
'mongodb://<hostname>:<port>',
144+
$uriOptions,
145+
);
122146

123-
.. _php-verify-auth-mechanism:
147+
To learn more about specifying authentication mechanisms, see the :ref:`php-auth`
148+
section.
124149

125-
.. replacement:: authsource-param-code-block
150+
Verify User Is in Authentication Database
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
126152

127-
.. code-block:: php
128-
:copyable: false
153+
When using a username and password-based authentication method,
154+
the username must be defined in the authentication database.
129155

130-
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=users';
131-
$client = new MongoDB\Client($uri);
156+
The default authentication database is the ``admin`` database.
157+
To use a different database for authentication, specify the
158+
``authSource`` option in the connection string.
132159

133-
.. replacement:: dns-resolution-anchor
160+
The following example instructs MongoDB to use the ``users`` database
161+
as the authentication database:
134162

135-
.. _java-dns-resolution-error:
163+
.. code-block:: php
164+
:copyable: false
136165

137-
.. replacement:: dns-error-message
166+
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=users';
167+
$client = new MongoDB\Client($uri);
138168

139-
.. code-block:: none
140-
:copyable: false
169+
DNS Resolution Errors
170+
---------------------
141171

142-
No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '<host>'].
172+
The {+driver-short+} may be unable to resolve your DNS connection. When this
173+
happens, you might receive an error message similar to the following message:
143174

144-
.. replacement:: check-the-number-of-connections-anchor
175+
.. code-block:: none
176+
:copyable: false
145177

146-
.. _php-connection-num-connections:
178+
No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '<host>'].
147179

148-
.. replacement:: mongo-client-class
180+
If the driver reports this error, try the methods in the following sections
181+
to resolve the issue.
149182

150-
``MongoDB\Client``
183+
Check Database Deployment Availability
184+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
151185

152-
.. replacement:: max-pool-size-param
186+
If you are connecting to MongoDB Atlas and your driver cannot find the DNS
187+
host of the Atlas database deployment, the database deployment might be paused
188+
or deleted.
153189

154-
``maxPoolSize``
190+
Ensure that the database deployment exists in Atlas. If the cluster is paused,
191+
you can resume the cluster in the Atlas UI or the
192+
:atlas:`Atlas command line interface </cli/stable/>`.
155193

156-
.. replacement:: max-pool-size-default
194+
To learn how to resume a cluster, see
195+
:atlas:`Resume One Cluster </pause-terminate-cluster/#resume-one-cluster/>`
196+
in the Atlas documentation.
157197

158-
``100``
198+
Check the Network Addresses
199+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
159200

160-
.. replacement:: max-idle-time-param
201+
Verify that the network addresses or hostnames in your connection string
202+
are accurate.
161203

162-
``maxIdleTimeMS``
163-
164-
.. replacement:: scram-failure-error
165-
166-
.. code-block::
167-
168-
Authentication failed.
169-
170-
.. replacement:: check-credentials-formatting-anchor
171-
172-
.. _php-troubleshooting-connection-string-auth:
173-
174-
.. replacement:: connection-pools-learn-more
204+
If your deployment is hosted on MongoDB Atlas, you can follow the
205+
:atlas:`Connect to Your Cluster </tutorial/connect-to-your-cluster/>`
206+
tutorial to find your Atlas connection string.

0 commit comments

Comments
 (0)