Docs Menu
Docs Home
/
Languages
/
Rust
/
Rust Driver

Connection Troubleshooting

On this page

  • Server Connection Errors
  • Check the Connection String
  • Configure the Firewall
  • Check the Number of Connections
  • Authentication Errors
  • Check the Credentials Formatting
  • Verify the Authentication Mechanism
  • Verify User Is in Authentication Database
  • DNS Resolution Errors
  • Check Database Deployment Availability
  • Check the Network Addresses

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

Note

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

  • The Frequently Asked Questions (FAQ) section for common questions and corresponding answers about the Rust driver

Server Connection Errors

When an issue occurs when you attempt to connect to a server, the Rust driver returns an error message. If this error resembles the following message, it indicates that the driver cannot connect to a MongoDB deployment:

Error: Error { kind: ServerSelection { message: "Server selection timeout:
No available servers. Topology: { Type: Unknown, Servers: [ { Address:
127.0.0.1:27017, 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.

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 driver to establish a connection if one of the hosts is unreachable.

To learn more about specifying multiple hosts in a replica set, see the Connect to a Replica Set section of the Connection 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.

Check the Number of Connections

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 the number of open connections is 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.

To learn more about how connection pools work in the driver, see How Does Connection Pooling Work in the Rust Driver? on the FAQ page.

Authentication Errors

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

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.

Check the Credentials Formatting

One of the most common causes of authentication issues is invalid credentials formatting in the MongoDB connection string.

Tip

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 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.

Alternatively, you can specify your authentication credentials in a Credential struct.

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

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:

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

DNS Resolution Errors

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 the driver 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.

Back

FAQ

Next

Operation Error Handling