mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Argument "replacement" must be an object

Error message

Argument "replacement" must be an object

What it means

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.

Solutions

1. Pass a plain object as the replacement document containing the new field values.
2. Ensure the replacement is a non-null object; default to {} if you intend an empty replacement (though unusual).
3. Do not confuse replacement (full document) with update ($ operators); use the correct API.

Example fix

// before
await collection.findOneAndReplace({ _id: id }, undefined);

// after
await collection.findOneAndReplace({ _id: id }, { name: 'new', value: 42 });

function isNonNullObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null;
}
if (!isNonNullObject(replacement)) {
  throw new TypeError('replacement document must be a plain object');
}
await collection.findOneAndReplace(filter, replacement);

function isNonNullObject(v: unknown): v is Record<string, unknown> {
  return typeof v === 'object' && v !== null;
}

When it happens

Trigger: Calling collection.findOneAndReplace(filter, null) or with a primitive/array second argument instead of a replacement document.

Common situations: Forgetting the replacement argument; passing an update-style pipeline where a replacement is expected; building the replacement from optional input that resolved to undefined.

Related errors

• Replacement document must not contain atomic operators
• Replacement document must not contain atomic operators
• Argument "filter" must be an object
• Argument "update" must be an object
• Profiling level must be one of

AI-assisted analysis of mongodb/node-mongodb-native@dce7939f86 (2026-08-11). Data as JSON: /api/errors/29e259707377c2ff. Report an issue: GitHub.

Appendix: source

Thrown at src/operations/find_and_modify.ts:236

    return document;
  }
}

/** @internal */
export class FindOneAndReplaceOperation extends FindAndModifyOperation {
  private replacement: Document;
  constructor(
    collection: Collection,
    filter: Document,
    replacement: Document,
    options: FindOneAndReplaceOptions
  ) {
    if (filter == null || typeof filter !== 'object') {
      throw new MongoInvalidArgumentError('Argument "filter" must be an object');
    }

    if (replacement == null || typeof replacement !== 'object') {
      throw new MongoInvalidArgumentError('Argument "replacement" must be an object');
    }

    if (hasAtomicOperators(replacement)) {
      throw new MongoInvalidArgumentError('Replacement document must not contain atomic operators');
    }

    super(collection, filter, options);
    this.replacement = replacement;
  }

  override buildCommandDocument(
    connection: Connection,
    session?: ClientSession
  ): Document & FindAndModifyCmdBase {
    const document = super.buildCommandDocument(connection, session);
    document.update = this.replacement;
    configureFindAndModifyCmdBaseUpdateOpts(document, this.options);
    return document;

View on GitHub (pinned to dce7939f86)