mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Bulk find operation must specify a selector

Error message

Bulk find operation must specify a selector

What it means

Thrown by BulkOperationBase.find(selector) when the selector argument is falsy (undefined, null, 0, '', false). Every bulk operation that targets existing documents needs a query filter; an empty/missing filter would implicitly match all docs and the driver requires an explicit selector to prevent accidental full-collection operations.

Source

Thrown at src/bulk/common.ts:1057

   *
   * // Add a multi deletion
   * bulkOp.find({ h: 8 }).delete();
   *
   * // Add a replaceOne
   * bulkOp.find({ i: 9 }).replaceOne({writeConcern: { j: 10 }});
   *
   * // Update using a pipeline
   * bulk.find({ k: 11, y: { $exists: true }, z: { $exists: true } }).updateOne([
   *   { $set: { total: { $sum: [ '$y', '$z' ] } } }
   * ]);
   *
   * // All of the ops will now be executed
   * await bulkOp.execute();
   * ```
   */
  find(selector: Document): FindOperators {
    if (!selector) {
      throw new MongoInvalidArgumentError('Bulk find operation must specify a selector');
    }

    // Save a current selector
    this.s.currentOp = {
      selector: selector
    };

    return new FindOperators(this);
  }

  /** Specifies a raw operation to perform in the bulk write. */
  raw(op: AnyBulkWriteOperation): this {
    if (op == null || typeof op !== 'object') {
      throw new MongoInvalidArgumentError('Operation must be an object with an operation key');
    }
    if ('insertOne' in op) {
      const forceServerObjectId = this.shouldForceServerObjectId();
      const document =

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pass an explicit selector, even an empty object {} matches all documents intentionally: bulk.find({}).
2. Guard dynamic selectors: if (!selector) throw new Error('selector required') before calling find.
3. Verify the variable feeding find() is actually defined at runtime.

Example fix

// before
const filter = maybeGetFilter(); // returns undefined
bulk.find(filter).updateOne({ $set: { a: 1 } });

// after
const filter = maybeGetFilter() ?? {};
bulk.find(filter).updateOne({ $set: { a: 1 } });

function findSafe(bulk, selector) {
  if (selector == null) {
    throw new TypeError('bulk.find() requires a selector; pass {} to match all');
  }
  return bulk.find(selector);
}

function isNonEmptySelector(sel) {
  return sel != null && typeof sel === 'object';
}

try {
  bulk.find(selector).updateOne({ $set: { a: 1 } });
} catch (e) {
  if (e instanceof MongoInvalidArgumentError && /selector/.test(e.message)) {
    selector = {};
    bulk.find(selector).updateOne({ $set: { a: 1 } });
  }
}

When it happens

Trigger: Calling bulk.find(undefined) or bulk.find(null). Calling bulk.find(someVar) where someVar was never assigned. Calling bulk.find() with no argument.

Common situations: Dynamic filter building where the filter object is conditionally constructed and ends up undefined; refactoring that drops the selector; passing a destructured value that was undefined.

Related errors

• Update document requires atomic operators
• Replacement document must not use atomic operators
• Operation must be an object with an operation key
• Invalid BulkOperation, Batch cannot be empty
• Selector must be a valid JavaScript object

AI-assisted analysis of mongodb/node-mongodb-native@3366c21a63 (2026-08-04). Data as JSON: /data/errors/3f944425ec7bdf72.json. Report an issue: GitHub.