mongodb/node-mongodb-native · error · MongoInvalidArgumentError

Operation "skip" requires an integer

Error message

Operation "skip" requires an integer

What it means

Thrown by FindCursor.skip when the value argument is not of type 'number'. The server requires an integer skip count and the driver type-checks before storing it on findOptions. Strings, booleans, undefined, and objects are rejected.

Solutions

1. Coerce and validate: const n = Number(value); if (!Number.isFinite(n)) throw ...; cursor.skip(n).
2. Pass skip through find options: collection.find({}, { skip: 20 }).
3. Guard the call: if (typeof value === 'number') cursor.skip(value).

Example fix

// before
cursor.skip(req.query.offset); // string

// after
const skip = Number(req.query.offset);
if (Number.isFinite(skip)) cursor.skip(skip);

function safeSkip(cursor, value) {
  const n = Number(value);
  if (!Number.isFinite(n)) throw new TypeError('skip must be a finite number');
  return cursor.skip(n);
}

function isFiniteInteger(v) { return typeof v === 'number' && Number.isFinite(v) && Number.isInteger(v); }

When it happens

Trigger: cursor.skip('20'); cursor.skip(parseInt(input)) returning NaN; cursor.skip(undefinedVar); passing pagination offset typed as string | number without narrowing.

Common situations: Pagination offsets from URL query strings; Number/parseInt returning NaN; optional config fields destructured without a default.

Related errors

• Argument for maxAwaitTimeMS must be a number
• Argument for maxTimeMS must be a number
• Operation "limit" requires an integer
• Tailable cursor does not support skip
• AuthMechanismProperties must be an object

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

Appendix: source

Thrown at src/cursor/find_cursor.ts:491

    }

    this.findOptions.limit = value;
    return this;
  }

  /**
   * Set the skip for the cursor.
   *
   * @param value - The skip for the cursor query.
   */
  skip(value: number): this {
    this.throwIfInitialized();
    if (this.findOptions.tailable) {
      throw new MongoTailableCursorError('Tailable cursor does not support skip');
    }

    if (typeof value !== 'number') {
      throw new MongoInvalidArgumentError('Operation "skip" requires an integer');
    }

    this.findOptions.skip = value;
    return this;
  }
}

View on GitHub (pinned to dce7939f86)