{"record":{"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/dce7939f86fb283e167ad709955abedb7bf23124/src/operations/execute_operation.ts#L271-L307","documentation":"Thrown as a MongoServerError when a write operation fails with the server error code IllegalOperation (the MMAPv1 retry-writes code) while retryWrites is enabled. The message instructs the user to disable retryWrites because the target deployment's storage engine (MMAPv1) or topology does not support retryable writes, which require WiredTiger and MongoDB 3.6+ replica set / 4.2+ sharded deployments. It is the user-facing rendering of MMAPv1_RETRY_WRITES_ERROR_MESSAGE.","triggerScenarios":"Connecting with retryWrites=true (the driver default for supported topologies) against a standalone server, an MMAPv1 storage engine deployment, or a pre-3.6 server, then performing any acknowledged single-document write (insertOne, updateOne, replaceOne, findOneAndUpdate, etc.). The first retryable write attempt returns code IllegalOperation and is rethrown at execute_operation.ts:289.","commonSituations":"Local development against a standalone mongod (no replica set); old MongoDB versions (<3.6); explicitly configuring retryWrites=true in the URI; running against a server that still uses the deprecated MMAPv1 storage engine.","solutions":["Add retryWrites=false to your connection string (e.g. mongodb://host:27017/?retryWrites=false).","Run MongoDB as a replica set (or sharded cluster) with the WiredTiger storage engine, which supports retryable writes.","Upgrade MongoDB to 3.6+ (replica set) or 4.2+ (sharded) where retryable writes are supported.","If using a managed service, confirm the deployment topology supports retryable writes."],"exampleFix":"// before\nconst uri = 'mongodb://localhost:27017/?retryWrites=true';\n\n// after\nconst uri = 'mongodb://localhost:27017/?retryWrites=false';","handlingStrategy":"validation","validationCode":"import { MongoClient } from 'mongodb';\n\nfunction buildUri(base: string) {\n  const u = new URL(base);\n  // For standalone / MMAPv1 deployments, retryable writes are unsupported\n  if (u.searchParams.get('retryWrites') === 'true') {\n    u.searchParams.set('retryWrites', 'false');\n  }\n  return u.toString();\n}\nconst client = new MongoClient(buildUri('mongodb://localhost:27017/?retryWrites=true'));","typeGuard":null,"tryCatchPattern":"try {\n  await client.db().command({ ping: 1 });\n} catch (err) {\n  if (err instanceof MongoServerError && /retryWrites=false/.test(err.message)) {\n    // add retryWrites=false to the URI and reconnect\n  } else throw err;\n}","preventionTips":["Know your deployment topology before enabling retryWrites.","Prefer replica-set/sharded deployments in production to keep retryWrites on by default.","Do not set retryWrites=true against standalone mongod instances."],"tags":["retryable-writes","configuration","storage-engine","topology","connection-string"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}