Skip to content

Commit 8e52a11

Browse files
norareidynorareidy
authored
DOCSP-50185: Connection troubleshooting (#272)
* DOCSP-50185: Connection troubleshooting * edits * remove sharedinclude * fix * wording * fix * MM feedback
1 parent 7f8c17b commit 8e52a11

File tree

3 files changed

+207
-3
lines changed

3 files changed

+207
-3
lines changed

‎source/connect.txt

Lines changed: 0 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,8 +26,6 @@ Connect to MongoDB
2626
Choose a Connection Target </connect/connection-targets>
2727
Connection Options </connect/connection-options>
2828
Connect with AWS Lambda </connect/aws-lambda>
29-
30-
.. TODO:
3129
Connection Troubleshooting </connect/connection-troubleshooting>
3230

3331
Overview

‎source/connect/connection-options.txt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Set Connection Options
3434
You can configure your connection by specifying options in the connection URI or by
3535
passing them to the ``MongoDB\Client`` constructor.
3636

37-
.. _php-connection-uri:
37+
.. _php-connection-options-uri:
3838

3939
Using the Connection URI
4040
~~~~~~~~~~~~~~~~~~~~~~~~

‎source/connect/connection-troubleshooting.txt

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
.. _php-connection-troubleshooting:
2+
3+
==========================
4+
Connection Troubleshooting
5+
==========================
6+
7+
.. contents:: On this page
8+
:local:
9+
:backlinks: none
10+
:depth: 2
11+
:class: singlecol
12+
13+
.. facet::
14+
:name: genre
15+
:values: reference
16+
17+
.. meta::
18+
:keywords: code example, disconnected, deployment
19+
20+
This page offers potential solutions to issues that you might encounter
21+
when using the {+library-short+} to connect to a MongoDB deployment.
22+
23+
.. note::
24+
25+
This page addresses only connection issues. If you encounter other
26+
issues when using MongoDB or the {+library-short+}, visit the following resources:
27+
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
33+
34+
Server Connection Errors
35+
------------------------
36+
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 library cannot connect to a MongoDB deployment:
40+
41+
.. code-block:: none
42+
:copyable: false
43+
44+
No suitable servers found (`serverSelectionTryOnce` set):
45+
[connection refused calling hello on 'localhost:27017']
46+
47+
The following sections describe methods that might help resolve the issue.
48+
49+
Check the Connection URI
50+
~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+
Verify that the hostname and port number in the connection URI 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 a {+mdb-server+} deployment is
55+
``27017``, but you can configure MongoDB to listen on another port.
56+
57+
When connecting to a replica set, include all the replica set hosts in
58+
your connection URI. Separate each of the hosts in the connection
59+
string with a comma. This enables the library to establish a connection if
60+
one of the hosts is unreachable.
61+
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.
65+
66+
Configure the Firewall
67+
~~~~~~~~~~~~~~~~~~~~~~
68+
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.
74+
75+
.. warning::
76+
77+
Do not open a firewall port unless you are sure that it is the one
78+
that your MongoDB deployment listens on.
79+
80+
Authentication Errors
81+
---------------------
82+
83+
The {+driver-short+} may be unable connect to a MongoDB deployment if
84+
the authorization is not configured correctly. In these cases, the library
85+
raises an error message similar to the following message:
86+
87+
.. code-block:: none
88+
:copyable: false
89+
90+
Authentication failed.
91+
92+
The following sections describe methods that may help resolve the issue.
93+
94+
Check the Credentials Formatting
95+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
96+
97+
One of the most common causes of authentication issues is invalid
98+
credentials formatting in the MongoDB connection URI.
99+
100+
.. tip::
101+
102+
To learn more information about using connection URIs,
103+
see :ref:`Connection URI <php-connection-uri>` in the
104+
Create a MongoDB Client guide.
105+
106+
If your connection URI contains a username and password, ensure that
107+
they are correctly formatted.
108+
109+
.. note::
110+
111+
You must `percent-encode <https://tools.ietf.org/html/rfc3986#section-2.1>`__
112+
the following characters if they appear in your username or password:
113+
114+
.. code-block:: none
115+
:copyable: false
116+
117+
: / ? # [ ] @
118+
119+
Use your percent-encoded username and password in your connection URI.
120+
121+
Verify the Authentication Mechanism
122+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
123+
124+
Ensure that your credentials and authentication mechanism are correct. You can
125+
specify your authentication credentials in the options of your connection URI.
126+
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:
131+
132+
.. code-block:: php
133+
:copyable: false
134+
135+
$uriOptions = [
136+
'username' => '<username>',
137+
'password' => '<password>',
138+
'authSource' => '<authentication database>',
139+
'authMechanism' => 'SCRAM-SHA-1',
140+
];
141+
142+
$client = new MongoDB\Client(
143+
'mongodb://<hostname>:<port>',
144+
$uriOptions,
145+
);
146+
147+
To learn more about specifying authentication mechanisms, see the :ref:`php-auth`
148+
section.
149+
150+
Verify User Is in Authentication Database
151+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
152+
153+
When using a username and password-based authentication method,
154+
the username must be defined in the authentication database.
155+
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 URI.
159+
160+
The following example instructs MongoDB to use the ``users`` database
161+
as the authentication database:
162+
163+
.. code-block:: php
164+
:copyable: false
165+
166+
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=users';
167+
$client = new MongoDB\Client($uri);
168+
169+
DNS Resolution Errors
170+
---------------------
171+
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:
174+
175+
.. code-block:: none
176+
:copyable: false
177+
178+
No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '<host>'].
179+
180+
If the library reports this error, try the methods in the following sections
181+
to resolve the issue.
182+
183+
Check Database Deployment Availability
184+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
185+
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.
189+
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/>`.
193+
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.
197+
198+
Check the Network Addresses
199+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
200+
201+
Verify that the network addresses or hostnames in your connection URI
202+
are accurate.
203+
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 URI.

0 commit comments

Comments
 (0)