{"record":{"id":"29e259707377c2ff","repo":"mongodb/node-mongodb-native","slug":"argument-replacement-must-be-an-object","errorCode":null,"errorMessage":"Argument \"replacement\" must be an object","messagePattern":"Argument \"replacement\" must be an object","errorType":"exception","errorClass":"MongoInvalidArgumentError","httpStatus":null,"severity":"error","filePath":"src/operations/find_and_modify.ts","lineNumber":236,"sourceCode":"    return document;\n  }\n}\n\n/** @internal */\nexport class FindOneAndReplaceOperation extends FindAndModifyOperation {\n  private replacement: Document;\n  constructor(\n    collection: Collection,\n    filter: Document,\n    replacement: Document,\n    options: FindOneAndReplaceOptions\n  ) {\n    if (filter == null || typeof filter !== 'object') {\n      throw new MongoInvalidArgumentError('Argument \"filter\" must be an object');\n    }\n\n    if (replacement == null || typeof replacement !== 'object') {\n      throw new MongoInvalidArgumentError('Argument \"replacement\" must be an object');\n    }\n\n    if (hasAtomicOperators(replacement)) {\n      throw new MongoInvalidArgumentError('Replacement document must not contain atomic operators');\n    }\n\n    super(collection, filter, options);\n    this.replacement = replacement;\n  }\n\n  override buildCommandDocument(\n    connection: Connection,\n    session?: ClientSession\n  ): Document & FindAndModifyCmdBase {\n    const document = super.buildCommandDocument(connection, session);\n    document.update = this.replacement;\n    configureFindAndModifyCmdBaseUpdateOpts(document, this.options);\n    return document;","sourceCodeStart":218,"sourceCodeEnd":254,"githubUrl":"https://github.com/mongodb/node-mongodb-native/blob/dce7939f86fb283e167ad709955abedb7bf23124/src/operations/find_and_modify.ts#L218-L254","documentation":"Thrown as a MongoInvalidArgumentError by the FindOneAndReplaceOperation constructor when the replacement document is null, undefined, or not an object. The replacement is the full document that overwrites the matched document and must be a plain object. Guard at find_and_modify.ts:235.","triggerScenarios":"Calling collection.findOneAndReplace(filter, null) or with a primitive/array second argument instead of a replacement document.","commonSituations":"Forgetting the replacement argument; passing an update-style pipeline where a replacement is expected; building the replacement from optional input that resolved to undefined.","solutions":["Pass a plain object as the replacement document containing the new field values.","Ensure the replacement is a non-null object; default to {} if you intend an empty replacement (though unusual).","Do not confuse replacement (full document) with update ($ operators); use the correct API."],"exampleFix":"// before\nawait collection.findOneAndReplace({ _id: id }, undefined);\n\n// after\nawait collection.findOneAndReplace({ _id: id }, { name: 'new', value: 42 });","handlingStrategy":"type-guard","validationCode":"function isNonNullObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null;\n}\nif (!isNonNullObject(replacement)) {\n  throw new TypeError('replacement document must be a plain object');\n}\nawait collection.findOneAndReplace(filter, replacement);","typeGuard":"function isNonNullObject(v: unknown): v is Record<string, unknown> {\n  return typeof v === 'object' && v !== null;\n}","tryCatchPattern":null,"preventionTips":["Provide a complete replacement document object as the second argument.","Default optional replacement fields rather than passing undefined."],"tags":["validation","find-one-and-replace","replacement","argument"],"backgroundTag":null,"analyzedSha":"dce7939f86fb283e167ad709955abedb7bf23124","analyzedAt":"2026-08-11T04:54:53.215Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}