{"id":"3a81aef9d1b278f1","repo":"mongodb/node-mongodb-native","slug":"raw-operations-are-not-allowed","errorCode":null,"errorMessage":"Raw operations are not allowed","messagePattern":"Raw operations are not allowed","errorType":"validation","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/bulk/common.ts","lineNumber":1089,"sourceCode":"      throw new MongoInvalidArgumentError('Operation must be an object with an operation key');\n    }\n    if ('insertOne' in op) {\n      const forceServerObjectId = this.shouldForceServerObjectId();\n      const document =\n        op.insertOne && op.insertOne.document == null\n          ? // TODO(NODE-6003): remove support for omitting the `documents` subdocument in bulk inserts\n            (op.insertOne as Document)\n          : op.insertOne.document;\n\n      maybeAddIdToDocuments(this.collection, document, { forceServerObjectId });\n\n      return this.addToOperationsList(BatchType.INSERT, document);\n    }\n\n    if ('replaceOne' in op || 'updateOne' in op || 'updateMany' in op) {\n      if ('replaceOne' in op) {\n        if ('q' in op.replaceOne) {\n          throw new MongoInvalidArgumentError('Raw operations are not allowed');\n        }\n        const updateStatement = makeUpdateStatement(\n          op.replaceOne.filter,\n          op.replaceOne.replacement,\n          { ...op.replaceOne, multi: false }\n        );\n        if (hasAtomicOperators(updateStatement.u)) {\n          throw new MongoInvalidArgumentError('Replacement document must not use atomic operators');\n        }\n        return this.addToOperationsList(BatchType.UPDATE, updateStatement);\n      }\n\n      if ('updateOne' in op) {\n        if ('q' in op.updateOne) {\n          throw new MongoInvalidArgumentError('Raw operations are not allowed');\n        }\n        const updateStatement = makeUpdateStatement(op.updateOne.filter, op.updateOne.update, {\n          ...op.updateOne,","sourceCodeStart":1071,"sourceCodeEnd":1107,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/3366c21a6311e02f1be91da982f9b93d3cce99a0/src/bulk/common.ts#L1071-L1107","documentation":"Thrown by BulkOperationBase.raw() when a replaceOne operation uses the raw wire-protocol field 'q' (e.g. { replaceOne: { q: {...}, u: {...} } }). The driver only accepts the user-facing shape { filter, replacement }; raw server-side statement shapes are rejected to prevent ambiguity and double-encoding.","triggerScenarios":"Passing { replaceOne: { q: filter, u: replacement } } to bulk.raw(). Constructing operations from serialized server statements or log dumps that use q/u field names.","commonSituations":"Copying operation shapes from MongoDB profiler output, oplog entries, or older driver internals that expose the q/u keys.","solutions":["Rewrite the operation using the documented keys: { replaceOne: { filter: q, replacement: u } }.","If you have raw statements, convert them with a mapper before passing to bulk.raw()."],"exampleFix":"// before\nbulk.raw({ replaceOne: { q: { _id: 1 }, u: { name: 'a' } } });\n\n// after\nbulk.raw({ replaceOne: { filter: { _id: 1 }, replacement: { name: 'a' } } });","handlingStrategy":"validation","validationCode":"function toUserReplaceOne(op) {\n  if ('q' in op.replaceOne || 'u' in op.replaceOne) {\n    return { replaceOne: { filter: op.replaceOne.q, replacement: op.replaceOne.u } };\n  }\n  return op;\n}","typeGuard":"function isUserFacingReplaceOne(op) {\n  return 'replaceOne' in op && !('q' in op.replaceOne);\n}","tryCatchPattern":"try {\n  bulk.raw(op);\n} catch (e) {\n  if (/Raw operations are not allowed/.test(e.message)) {\n    op = normalizeOp(op); // map q/u -> filter/replacement\n    bulk.raw(op);\n  }\n}","preventionTips":["Always build operations using the documented { filter, replacement } keys.","Never paste operation shapes from profiler/oplog output directly into bulk.raw()."],"tags":["bulk-write","raw","replace","argument-error"],"analyzedSha":"3366c21a6311e02f1be91da982f9b93d3cce99a0","analyzedAt":"2026-08-04T13:40:15.335Z","schemaVersion":2}