Retryable Writes

Persistent Network Errors

MongoDB retryable writes make only one retry attempt. This helps address transient network errors and replica set elections, but not persistent network errors.

Failover Period

If the driver cannot find a healthy primary in the destination replica set or sharded cluster shard, the drivers wait serverSelectionTimeoutMS milliseconds to determine the new primary before retrying. Retryable writes do not address instances where the failover period exceeds serverSelectionTimeoutMS.

Duplicate Key Errors on Upsert

MongoDB 4.2 will retry single-document upsert operations (i.e upsert : true and multi : false) that fail due to a duplicate key error only if the operation meets all of the following conditions:

• The target collection has a unique index that caused the duplicate key error.

• The update match condition is either:

  • A single equality predicate

    { "fieldA" : "valueA" },

    or

  • a logical AND of equality predicates

    { "fieldA" : "valueA", "fieldB" : "valueB" }

• The set of fields in the unique index key pattern matches the set of fields in the update query predicate.

• The update operation does not modify any of the fields in the query predicate.

The following table contains examples of upsert operations that the server can or cannot retry on a duplicate key error:

{ _id : 1 }

db.collName.updateOne(
  { _id : ObjectId("1aa1c1efb123f14aaa167aaa") },
  { $set : { fieldA : 25 } },
  { upsert : true }
)

{ fieldA : 1 }

db.collName.updateOne(
  { fieldA : { $in : [ 25 ] } },
  { $set : { fieldB : "someValue" } },
  { upsert : true }
)

{
  fieldA : 1,
  fieldB : 1
}

db.collName.updateOne(
  { fieldA : 25, fieldB : "someValue" },
  { $set : { fieldC : false } },
  { upsert : true }
)

{ fieldA : 1 }

db.collName.updateOne(
  { fieldA : { $lte : 25 } },
  { $set : { fieldC : true } },
  { upsert : true }
)

{ fieldA : 1 }

db.collName.updateOne(
  { fieldA : { $in : [ 25 ] } },
  { $set : { fieldA : 20 } },
  { upsert : true }
)

{ _id : 1 }

db.collName.updateOne(
  { fieldA : { $in : [ 25 ] } },
  { $set : { fieldA : 20 } },
  { upsert : true }
)

{ fieldA : 1 }

db.collName.updateOne(
  { fieldA : 25, fieldC : true },
  { $set : { fieldD : false } },
  { upsert : true }
)

Prior to MongoDB 4.2, MongoDB retryable writes did not support retrying upserts which failed due to duplicate key errors.

Diagnostics

The serverStatus command, and its mongosh shell helper db.serverStatus() includes statistics on retryable writes in the transactions section.

Retryable Writes Against local Database

The official MongoDB 4.2-series drivers enable retryable writes by default. Applications which write to the local database will encounter write errors upon upgrading to 4.2-series drivers unless retryable writes are explicitly disabled.

To disable retryable writes, specify retryWrites=false in the connection string for the MongoDB cluster.

Error Handling

Starting in MongoDB 6.1, if both the first and second attempt of a retryable write fail without a single write being performed, MongoDB returns an error with the NoWritesPerformed label.

The NoWritesPerformed label differentiates the results of batch operations like insertMany(). In an insertMany operation, one of the following outcomes can occur:

Applications can use the NoWritesPerformed label to definitively determine that no documents were inserted. This error reporting lets the application maintain an accurate state of the database when handling retryable writes.

In previous versions of MongoDB, an error is returned when both the first and second attempts of a retryable write fail. However, there is no distinction made to indicate that no writes were performed.