{"id":"c63ddc841faa3019","repo":"mongodb/node-mongodb-native","slug":"replacement-document-must-not-use-atomic-operators","errorCode":null,"errorMessage":"Replacement document must not use atomic operators","messagePattern":"Replacement document must not use atomic operators","errorType":"validation","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/bulk/common.ts","lineNumber":749,"sourceCode":"  }\n\n  /** Add a single update operation to the bulk operation */\n  updateOne(updateDocument: Document | Document[]): BulkOperationBase {\n    if (!hasAtomicOperators(updateDocument, this.bulkOperation.bsonOptions)) {\n      throw new MongoInvalidArgumentError('Update document requires atomic operators');\n    }\n\n    const currentOp = buildCurrentOp(this.bulkOperation);\n    return this.bulkOperation.addToOperationsList(\n      BatchType.UPDATE,\n      makeUpdateStatement(currentOp.selector, updateDocument, { ...currentOp, multi: false })\n    );\n  }\n\n  /** Add a replace one operation to the bulk operation */\n  replaceOne(replacement: Document): BulkOperationBase {\n    if (hasAtomicOperators(replacement)) {\n      throw new MongoInvalidArgumentError('Replacement document must not use atomic operators');\n    }\n\n    const currentOp = buildCurrentOp(this.bulkOperation);\n    return this.bulkOperation.addToOperationsList(\n      BatchType.UPDATE,\n      makeUpdateStatement(currentOp.selector, replacement, { ...currentOp, multi: false })\n    );\n  }\n\n  /** Add a delete one operation to the bulk operation */\n  deleteOne(): BulkOperationBase {\n    const currentOp = buildCurrentOp(this.bulkOperation);\n    return this.bulkOperation.addToOperationsList(\n      BatchType.DELETE,\n      makeDeleteStatement(currentOp.selector, { ...currentOp, limit: 1 })\n    );\n  }\n","sourceCodeStart":731,"sourceCodeEnd":767,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/bulk/common.ts#L731-L767","documentation":"Thrown by FindOperators.replaceOne() when the replacement document contains atomic operators. A replacement document must be a plain object whose fields replace the existing document wholesale; mixing in $set/$inc etc. is illegal because the server would reject the command. hasAtomicOperators() returns true when the first key starts with '$'.","triggerScenarios":"Calling bulk.find(filter).replaceOne({ $set: {...} }) or any replaceOne where the first key is a $-operator. Copy-pasting an update document into a replaceOne call site.","commonSituations":"Refactoring between updateOne and replaceOne without adjusting the document shape; building documents generically and routing them to the wrong method.","solutions":["Strip the atomic operator and pass a plain replacement: { $set: { a: 1 } } -> { a: 1 }.","If you actually want partial update semantics, switch to updateOne/updateMany instead of replaceOne."],"exampleFix":"// before\nbulk.find({ _id: 1 }).replaceOne({ $set: { name: 'alice' } });\n\n// after\nbulk.find({ _id: 1 }).replaceOne({ name: 'alice' });","handlingStrategy":"validation","validationCode":"function isPlainReplacement(doc) {\n  return doc != null && typeof doc === 'object' &&\n    Object.keys(doc).every(k => k[0] !== '$');\n}","typeGuard":"function isReplacementDoc(doc) {\n  return (\n    doc != null &&\n    typeof doc === 'object' &&\n    !Array.isArray(doc) &&\n    (Object.keys(doc).length === 0 || Object.keys(doc)[0][0] !== '$')\n  );\n}","tryCatchPattern":"try {\n  bulk.find(filter).replaceOne(rep);\n} catch (e) {\n  if (e instanceof MongoInvalidArgumentError && /must not use atomic/.test(e.message)) {\n    // strip $-wrapper or route to updateOne\n  }\n  throw e;\n}","preventionTips":["Treat replaceOne and updateOne as semantically distinct; never share document builders between them.","In code review, flag any $-prefixed key inside a replaceOne payload."],"tags":["bulk-write","replace","validation","argument-error"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}