mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Argument "filter" must be an object

Error message

Argument "filter" must be an object

What it means

FindOneAndDeleteOperation's constructor (src/operations/find_and_modify.ts:206) requires the `filter` argument to be a non-null object. Passing null, undefined, a primitive, or an array throws a MongoInvalidArgumentError before any server round-trip. This validates the query that selects the document to delete.

Source

Thrown at src/operations/find_and_modify.ts:206

    if (options.hint) {
      command.hint = options.hint;
    }

    return command;
  }

  override handleOk(response: InstanceType<typeof this.SERVER_COMMAND_RESPONSE_TYPE>): Document {
    const result = super.handleOk(response);
    return this.options.includeResultMetadata ? result : (result.value ?? null);
  }
}

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

    super(collection, filter, options);
  }

  override buildCommandDocument(
    connection: Connection,
    session?: ClientSession
  ): Document & FindAndModifyCmdBase {
    const document = super.buildCommandDocument(connection, session);
    document.remove = true;
    return document;
  }
}

/** @internal */
export class FindOneAndReplaceOperation extends FindAndModifyOperation {
  private replacement: Document;

View on GitHub (pinned to 3366c21a63)

Solutions

1. Pass a plain object filter, e.g. collection.findOneAndDelete({ _id }).
2. If you intend to match all, pass an empty object {} (though findOneAndDelete on {} deletes an arbitrary document).
3. Ensure the filter variable is defined before the call.

Example fix

// before
await collection.findOneAndDelete(); // undefined filter

// after
await collection.findOneAndDelete({ _id: targetId });

function assertFilter(filter: unknown): asserts filter is Record<string, unknown> {
  if (filter == null || typeof filter !== 'object' || Array.isArray(filter)) {
    throw new TypeError('findOneAndDelete: filter must be a plain object');
  }
}

const isValidFilter = (f: unknown): f is Record<string, unknown> =>
  f != null && typeof f === 'object' && !Array.isArray(f);

When it happens

Trigger: Calling collection.findOneAndDelete(null), collection.findOneAndDelete(undefined), collection.findOneAndDelete('id'), or collection.findOneAndDelete([cond]).

Common situations: Omitting the filter argument by mistake, passing a raw ID string instead of {_id: id}, or destructuring undefined from a function parameter.

Related errors

• Query filter must be a plain object or ObjectId
• Argument "replacement" must be an object
• Replacement document must not contain atomic operators
• Argument "update" must be an object
• Bulk find operation must specify a selector

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