{"id":"cf2419c1d6e7ed9d","repo":"mongodb/node-mongodb-native","slug":"this-mongodb-deployment-does-not-support-retryable","errorCode":null,"errorMessage":"This MongoDB deployment does not support retryable writes. Please add retryWrites=false to your connection string.","messagePattern":"This MongoDB deployment does not support retryable writes\\. Please add retryWrites=false to your connection string\\.","errorType":"exception","errorClass":"MongoServerError","httpStatus":null,"severity":"error","filePath":"src/operations/execute_operation.ts","lineNumber":289,"sourceCode":"    } catch (operationError) {\n      // Should never happen but if it does - propagate the error.\n      if (!(operationError instanceof MongoError)) throw operationError;\n\n      // Preserve the original error once a write has been performed.\n      // Only update to the latest error if no writes were performed.\n      if (error == null) {\n        error = operationError;\n      } else {\n        if (!operationError.hasErrorLabel(MongoErrorLabel.NoWritesPerformed)) {\n          error = operationError;\n        }\n      }\n\n      // Reset timeouts\n      timeoutContext.clear();\n\n      if (hasWriteAspect && operationError.code === MMAPv1_RETRY_WRITES_ERROR_CODE) {\n        throw new MongoServerError({\n          message: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,\n          errmsg: MMAPv1_RETRY_WRITES_ERROR_MESSAGE,\n          originalError: operationError\n        });\n      }\n\n      if (!canRetry(operation, operationError)) {\n        throw error;\n      }\n\n      if (operationError.hasErrorLabel(MongoErrorLabel.SystemOverloadedError)) {\n        const maxOverloadAttempts = topology.s.options.maxAdaptiveRetries + 1;\n        maxAttempts = Math.min(maxOverloadAttempts, operation.maxAttempts ?? maxOverloadAttempts);\n      }\n\n      if (attempt + 1 >= maxAttempts) {\n        throw error;\n      }","sourceCodeStart":271,"sourceCodeEnd":307,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/operations/execute_operation.ts#L271-L307","documentation":"In executeOperationWithRetries (src/operations/execute_operation.ts:289), when a write operation fails with code IllegalOperation (the MMAPv1 retry-writes error), the driver throws a MongoServerError with a fixed message instructing the user to disable retryWrites. MMAPv1 and certain pre-4.0 standalone deployments cannot support retryable writes, and retryWrites defaults to true.","triggerScenarios":"Running a write operation (insert/update/delete/findOneAndUpdate/etc.) with the default retryWrites=true against a deployment whose storage engine or topology does not support retryable writes — most notably MMAPv1 or a standalone server.","commonSituations":"Legacy MongoDB 3.x standalone, a replica set with MMAPv1 storage engine, or a misconfigured test instance. The default retryWrites=true in modern drivers triggers this on incompatible deployments.","solutions":["Add retryWrites=false to the connection string as the message instructs.","Upgrade the storage engine from MMAPv1 to WiredTiger (MongoDB 4.0+ default).","For a standalone server, switch to a replica set to gain retryable-writes support.","Verify the deployment version/topology with db.serverStatus().storageEngine."],"exampleFix":"// before\nconst uri = 'mongodb://localhost:27017'; // MMAPv1 standalone\nconst client = new MongoClient(uri);\nawait client.db().collection('x').insertOne({ a: 1 }); // throws\n\n// after\nconst uri = 'mongodb://localhost:27017/?retryWrites=false';\nconst client = new MongoClient(uri);\nawait client.db().collection('x').insertOne({ a: 1 });","handlingStrategy":"validation","validationCode":"// Detect incompatible deployment before writes\nconst admin = client.db().admin();\nconst status = await admin.command({ serverStatus: 1 });\nconst engine = status.storageEngine?.name;\nif (engine === 'mmapv1') {\n  // disable retryWrites in the URI: retryWrites=false\n}","typeGuard":null,"tryCatchPattern":"try {\n  await collection.insertOne(doc);\n} catch (err) {\n  if (err instanceof MongoServerError && /retryWrites=false/.test(err.message)) {\n    // reconnect with retryWrites=false or upgrade the deployment\n  } else throw err;\n}","preventionTips":["Add retryWrites=false to the connection string when targeting MMAPv1 or standalone deployments.","Prefer WiredTiger and replica-set/sharded topologies for retryable-writes support.","Verify storage engine with db.serverStatus().storageEngine.name."],"tags":["compatibility","retryable-writes","mmapv1","standalone","connection-string"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}