> For the complete MongoDB documentation index, see www.mongodb.com/docs/llms.txt

# Retryable Writes

Retryable writes let drivers retry specific write operations once after network errors or if they cannot find a healthy [primary](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-primary) in the [replica set](https://www.mongodb.com/docs/manual/replication.md#std-label-replication) or [sharded cluster.](https://www.mongodb.com/docs/manual/sharding.md#std-label-sharding-introduction)

## Compatibility

Retryable writes require:

Deployment Topologies

A [replica set](https://www.mongodb.com/docs/manual/replication.md#std-label-replication) or [sharded cluster](https://www.mongodb.com/docs/manual/sharding.md#std-label-sharding-introduction). Not supported on [standalone instances.](https://www.mongodb.com/docs/manual/reference/glossary.md#std-term-standalone)

Storage Engine

A storage engine with document-level locking, such as [WiredTiger](https://www.mongodb.com/docs/manual/core/wiredtiger.md#std-label-storage-wiredtiger) or [in-memory.](https://www.mongodb.com/docs/manual/core/inmemory.md#std-label-storage-inmemory)

MongoDB Drivers

Drivers compatible with MongoDB 3.6+.

| Java 3.6+ Python 3.6+ C 1.9+ Go 1.8+ | C# 2.5+ Node 3.0+ Ruby 2.5+ Rust 2.1+ Swift 1.2+ | Perl 2.0+ PHPC 1.4+ Scala 2.2+ C++ 3.6.6+ |
| --- | --- | --- |

MongoDB Version

MongoDB 3.6+ and `featureCompatibilityVersion` 3.6+ on all nodes. See [`setFeatureCompatibilityVersion`.](https://www.mongodb.com/docs/manual/reference/command/setfeaturecompatibilityversion.md#mongodb-dbcommand-dbcmd.setFeatureCompatibilityVersion)

Write Acknowledgment

Writes with [Write Concern](https://www.mongodb.com/docs/manual/reference/write-concern.md) `0` are not retryable.

## Behaviors

### Retryable Writes and Multi-Document Transactions

[Transaction commit and abort operations](https://www.mongodb.com/docs/manual/core/transactions-in-applications.md#std-label-transactions-retry) are retryable. Drivers retry these operations once on error, even if [`retryWrites`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites) is `false`.

Writes inside a transaction are not individually retryable, regardless of value of [`retryWrites`.](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites)

For more information on transactions, see [Transactions.](https://www.mongodb.com/docs/manual/core/transactions.md)

### Enabling Retryable Writes

MongoDB Drivers

Drivers compatible with MongoDB 4.2 and higher enable [Retryable Writes](https://www.mongodb.com/docs/manual/core/retryable-writes.md#std-label-retryable-writes) by default. Earlier drivers require the [`retryWrites=true`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites) option. The [`retryWrites=true`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites) option can be omitted in applications that use drivers compatible with MongoDB 4.2 and higher.

To disable retryable writes, applications that use drivers compatible with MongoDB 4.2 and higher must include [`retryWrites=false`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites) in the connection string.

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh)

[`mongosh`](https://www.mongodb.com/docs/mongodb-shell.md#mongodb-binary-bin.mongosh) enables retryable writes by default. To disable, use [`--retryWrites=false`:](https://www.mongodb.com/docs/mongodb-shell/reference/options.md#std-option-mongosh.--retryWrites)

```bash
mongosh --retryWrites=false
```

### Retryable Write Operations

MongoDB retries the following operations if they have acknowledged write concern (for example, [Write Concern](https://www.mongodb.com/docs/manual/reference/write-concern.md) cannot be [`{w: 0}`](https://www.mongodb.com/docs/manual/reference/write-concern.md#mongodb-writeconcern-writeconcern.-number-)):

**Note:**

Writes inside [transactions](https://www.mongodb.com/docs/manual/core/transactions.md) are not individually retryable.

| Methods | Descriptions |
| --- | --- |
| [`db.collection.insertOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertone.md#mongodb-method-db.collection.insertOne)[`db.collection.insertMany()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertmany.md#mongodb-method-db.collection.insertMany) | Inserts |
| [`db.collection.updateOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.updateone.md#mongodb-method-db.collection.updateOne)[`db.collection.replaceOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.replaceone.md#mongodb-method-db.collection.replaceOne) | Single-document updates |
| [`db.collection.deleteOne()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.deleteone.md#mongodb-method-db.collection.deleteOne)[`db.collection.remove()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.remove.md#mongodb-method-db.collection.remove) where `justOne` is `true` | Single-document deletes |
| [`db.collection.findAndModify()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findandmodify.md#mongodb-method-db.collection.findAndModify)[`db.collection.findOneAndDelete()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findoneanddelete.md#mongodb-method-db.collection.findOneAndDelete)[`db.collection.findOneAndReplace()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findoneandreplace.md#mongodb-method-db.collection.findOneAndReplace)[`db.collection.findOneAndUpdate()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.findoneandupdate.md#mongodb-method-db.collection.findOneAndUpdate) | `findAndModify` operations (always single-document). |
| [`db.collection.bulkWrite()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.bulkwrite.md#mongodb-method-db.collection.bulkWrite) with the following write operations: [insertOne](https://www.mongodb.com/docs/manual/reference/method/db.collection.bulkwrite.md#std-label-bulkwrite-write-operations-insertOne); [updateOne](https://www.mongodb.com/docs/manual/reference/method/db.collection.bulkwrite.md#std-label-bulkwrite-write-operations-updateOneMany); [replaceOne](https://www.mongodb.com/docs/manual/reference/method/db.collection.bulkwrite.md#std-label-bulkwrite-write-operations-replaceOne); [deleteOne](https://www.mongodb.com/docs/manual/reference/method/db.collection.bulkwrite.md#std-label-bulkwrite-write-operations-deleteOneMany) | Bulk write operations that only consist of the single-document write operations. A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as `updateMany`. |
| [`Bulk`](https://www.mongodb.com/docs/manual/reference/method/bulk.md#mongodb-method-Bulk) operations for: [`Bulk.find.removeOne()`](https://www.mongodb.com/docs/manual/reference/method/bulk.find.removeone.md#mongodb-method-Bulk.find.removeOne); [`Bulk.find.replaceOne()`](https://www.mongodb.com/docs/manual/reference/method/bulk.find.replaceone.md#mongodb-method-Bulk.find.replaceOne); [`Bulk.find.updateOne()`](https://www.mongodb.com/docs/manual/reference/method/bulk.find.updateone.md#mongodb-method-Bulk.find.updateOne) | Bulk write operations that only consist of the single-document write operations. A retryable bulk operation can include any combination of the specified write operations but cannot include any multi-document write operations, such as `update` which specifies `true` for the `multi` option. |

### Persistent Network Errors

By default, MongoDB retries writes **once**. One retry attempts to address transient network errors and [replica set elections](https://www.mongodb.com/docs/manual/core/replica-set-elections.md#std-label-replica-set-elections), but not persistent network errors.

If you set `timeoutMS`, MongoDB may retry writes multiple times. Retries continue until one of the following conditions is true:

- The operation succeeds.

- The operation fails with a non-retryable error.

- The timeout expires.

### Failover Period

Drivers wait [`serverSelectionTimeoutMS`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.serverSelectionTimeoutMS) to find a new primary before retrying. Retryable writes fail if failover takes longer than this timeout.

**Warning:**

If a client is unresponsive for longer than [`localLogicalSessionTimeoutMinutes`](https://www.mongodb.com/docs/manual/reference/parameters.md#mongodb-parameter-param.localLogicalSessionTimeoutMinutes), the write might retry and apply again when the client recovers.

### Diagnostics

[`serverStatus`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-dbcommand-dbcmd.serverStatus) includes retryable write statistics in the [`transactions`](https://www.mongodb.com/docs/manual/reference/command/serverstatus.md#mongodb-serverstatus-serverstatus.transactions) section.

### Retryable Writes Against `local` Database

Official drivers enable retryable writes by default. Writes to the `local` [database](https://www.mongodb.com/docs/manual/reference/local-database.md#std-label-replica-set-local-database) fail unless you disable retryable writes.

To disable, set [`retryWrites=false`](https://www.mongodb.com/docs/manual/reference/connection-string-options.md#mongodb-urioption-urioption.retryWrites) in the [connection string.](https://www.mongodb.com/docs/manual/reference/connection-string.md#std-label-mongodb-uri)

### 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()`](https://www.mongodb.com/docs/manual/reference/method/db.collection.insertmany.md#mongodb-method-db.collection.insertMany). In an `insertMany` operation, one of the following outcomes can occur:

| Outcome | MongoDB Output |
| --- | --- |
| No documents are inserted. | Error returned with `NoWritesPerformed` label. |
| Partial work done. (At least one document is inserted, but not all.) | Error returned without `NoWritesPerformed` label. |
| All documents are inserted. | Success returned. |

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.

## Learn More

[Retryable Reads](https://www.mongodb.com/docs/manual/core/retryable-reads.md#std-label-retryable-reads)