Connection Troubleshooting
This page offers potential solutions to issues that you might encounter when using the PHP library to connect to a MongoDB deployment.
Note
This page addresses only connection issues. If you encounter other issues when using MongoDB or the PHP library, visit the following resources:
The Issues & Help page for information about reporting bugs, contributing to the library, and finding more resources
The MongoDB Community Forums for questions, discussions, or general technical support
Server Connection Errors
When an issue occurs when you attempt to connect to a server, the PHP library returns an error message. If this error resembles the following message, it indicates that the library cannot connect to a MongoDB deployment:
No suitable servers found (`serverSelectionTryOnce` set): [connection refused calling hello on 'localhost:27017']
The following sections describe methods that might help resolve the issue.
Check the 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 an instance of MongoDB Server is
27017, but you can configure MongoDB to listen on another port.
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 library to establish a connection if one of the hosts is unreachable.
To learn how to specify multiple replica set hosts, see the Replica Sets section of the Choose a Connection Target guide.
Configure the Firewall
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.
Warning
Do not open a firewall port unless you are sure that it is the one that your MongoDB deployment listens on.
Authentication Errors
The PHP library may be unable connect to a MongoDB deployment if the authorization is not configured correctly. In these cases, the library raises an error message similar to the following message:
Authentication failed.
The following sections describe methods that may help resolve the issue.
Check the Credentials Formatting
One of the most common causes of authentication issues is invalid credentials formatting in the MongoDB connection string.
Tip
To learn more information about using connection strings, see Connection URI in the Create a MongoDB Client guide.
If your connection string contains a username and password, ensure that they are correctly formatted.
Note
If your username or password includes any of the following characters, you must percent-encode it:
: / ? # [ ] @
Use your percent-encoded username and password in your connection string.
Verify the Authentication Mechanism
Ensure that your credentials and authentication mechanism are correct. You can specify your authentication credentials in the options of your connection string.
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:
$uriOptions = [ 'username' => '<username>', 'password' => '<password>', 'authSource' => '<authentication database>', 'authMechanism' => 'SCRAM-SHA-1', ]; $client = new MongoDB\Client( 'mongodb://<hostname>:<port>', $uriOptions, );
To learn more about specifying authentication mechanisms, see the Authentication Mechanisms section.
Verify User Is in Authentication Database
When using a username and password-based authentication method, 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 MongoDB to use the users database
as the authentication database:
$uri = 'mongodb://<username>:<password>@<hostname>:<port>/?authSource=users'; $client = new MongoDB\Client($uri);
DNS Resolution Errors
The PHP library may be unable to resolve your DNS connection. When this happens, you might receive an error message similar to the following message:
No suitable servers found (`serverSelectionTryOnce` set): [Failed to resolve '<host>'].
If the library reports this error, try the methods in the following sections to resolve the issue.
Check Database Deployment Availability
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.
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 command line interface.
To learn how to resume a cluster, see Resume One Cluster in the Atlas documentation.
Check the Network Addresses
Verify that the network addresses or hostnames in your connection string are accurate.
If your deployment is hosted on MongoDB Atlas, you can follow the Connect to Your Cluster tutorial to find your Atlas connection string.