Docs Menu
Docs Home
/ / /
Rust Driver

Operation Error Handling

On this page

  • Overview
  • Error Type
  • Connection Errors
  • Write Error Types
  • Write Concern Error
  • Write Error

This page describes errors you might encounter when using the MongoDB Rust Driver to perform MongoDB operations. Once you understand the types of operation errors that the driver raises, you can take appropriate actions to either handle them or correct the error-causing code.


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

  • Connection Troubleshooting for potential solutions to issues you might encounter when connecting to a MongoDB deployment

  • 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

If the driver encounters an error while performing an operation, it returns an error of the Error type.

The Error type contains the kind field, which describes the type of error that occurred. The kind field has a value of enum ErrorKind. The ErrorKind enum has variants for different kinds of errors, including the following:

  • InvalidArgument: you provided an invalid argument to a method

  • Authentication: the driver encountered an error during authentication

  • ServerSelection: the client couldn't select a server for the operation

  • Write: an error occurred during a write operation

  • Transaction: an error occurred during a transaction

For example, if you attempt to perform an insert operation that duplicates an _id field value that is already in the collection, the driver returns an Error instance and prints the following error message:

Error: Error { kind: Write(WriteError(WriteError { code: 11000,
code_name: None, message: "E11000 duplicate key error collection:
db.test_coll index: _id_ dup key: { _id: 1 }", details: None })), labels:
{}, wire_version: None, source: None }

In the preceding error message, the value of the kind field is Write. To learn more about this type of error, see the Write Error Types section of this guide.

A concurrent operation error might clear the connection pool, interrupting your connection to the server. In this situation, the driver raises an Error type in which the value of the kind field is ConnectionPoolCleared. The error message describes the reason that the concurrent operation failed.

To learn how to adjust your connection pool to address this error, see Tuning Your Connection Pool Settings in the Server manual.

Depending on the circumstances that produce the error, the driver might add a RetryableWriteError label to the error, as shown in the following error message:

Error { kind: ConnectionPoolCleared { message: "Connection pool for
localhost:27017 cleared because another operation failed with: Kind:
I/O error: timed out, labels: {}" }, labels: {"RetryableWriteError"},
wire_version: None, source: None }

This label indicates that the error is write-retryable, which means that the driver makes one retry attempt.

When the driver experiences an error while performing a write operation, it raises an Error instance with a kind field value of Write. The body of the Write variant is the enum WriteFailure, which takes a value of type WriteError or WriteConcernError.

The driver raises a WriteConcernError error when you perform a write operation and the driver cannot satisfy the specified write concern. For example, if you specify a write concern of majority for operations on a replica set with three nodes, the driver returns this error if the write operation propagates only to one node.

To learn more about write concerns, see Write Concern in the Server manual.

The driver raises a WriteError error for any errors that it encounters when performing a write operation that are not related to satisfying the write concern. Because there are many causes for this error, the WriteError type contains fields that describe the type of write error and reason for the error.

For example, the driver raises a WriteError error if you attempt to insert a document into a collection that violates the collection's schema validation rules. Suppose the collection has a rule where the value of the quantity field must be an int type. If you attempt to insert a document where the value of quantity is "three", the driver prints the following error message:

Error: Error { kind: Write(WriteError(WriteError { code: 121, code_name:
None, message: "Document failed validation", details:
Some(Document({"failingDocumentId": Int32(1), "details":
Document({"operatorName": String("$jsonSchema"), "title":
String("Numerical Validation"), "schemaRulesNotSatisfied":
Array(...)})})) })), labels: {},
wire_version: None, source: None }

In the preceding error message, the message field describes the reason for the error, and the details field provides specific details about the failing operation. To address this error, you must either revise the document to adhere to the schema validation rules or bypass validation.

To learn more about schema validation, see the guide on Schema Validation.

← Connection Troubleshooting