Docs Menu

Docs HomeRust Driver

Connection Troubleshooting

On this page

  • Server Connection Error
  • Check Connection String
  • Configure Firewall
  • Check the Number of Connections
  • Authentication Error
  • Check Connection String
  • Verify the Authentication Mechanism
  • Verify User Is in Authentication Database
  • DNS Resolution Error
  • Check Database Deployment Availability
  • Check Connection String

This page offers potential solutions to issues you might encounter when using the MongoDB Rust Driver to connect to a MongoDB deployment.


This page only addresses connection issues. If you encounter any other issues with MongoDB or the driver, visit the following resources:

  • Operation Error Handling for recommendations on how to handle different error types that the driver raises during operations

  • 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

When you attempt to connect to a server, the Rust driver 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:

Error: Error { kind: ServerSelection { message: "Server selection timeout:
No available servers. Topology: { Type: Unknown, Servers: [ { Address:, Type: Unknown, Error: Kind: I/O error: Connection refused
(os error 61), labels: {} } ] }" }, labels: {}, wire_version: None, source:
None }

The following sections describe methods that might help resolve the issue.

Verify that the hostname and port number in the connection string are both accurate. In the sample error message, the hostname is 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.

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.


Do not open a port in your firewall unless you are sure that it is the port used by your MongoDB instance.

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.

The Rust driver 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:

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 }) }

The following sections describe methods that may help resolve the issue.

An invalid connection string is the most common cause of authentication issues when attempting to connect to MongoDB.


For more information about connection strings, see the Create a Connection String guide.

If your connection string contains a username and password, ensure that they are in the correct format.


If your username or password includes any of the following characters, you must percent encode it:

: / ? # [ ] @

After percent encoding your username and password, you can use them as credentials in your connection string.

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 Connect to a Replica Set in the Connection Guide.

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.

To learn more about authentication, see the Authentication Mechanisms guide.

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:

let uri = "mongodb://<username>:<password>@<hostname>:<port>/?authSource=users";
let client = Client::with_uri_str(uri).await?;

The Rust driver may be unable to resolve your DNS connection. When this happens, you might receive an error message similar to the following message:

Error: Error { kind: DnsResolve { message: "sample message. type:
SRV class: IN" }, labels: {}, wire_version: None, source: None }

If you receive this error, try the following methods to resolve the issue.

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.

To learn how to resume a cluster, see Resume One Cluster in the Atlas documentation.

Verify that the connection string in your app is accurate. For more information about verifying your connection string, see Connection Error and Authentication Error.

←  GridFSOperation Error Handling →
Share Feedback