mastra-ai/mastra · error

page value too large

Error message

page value too large

What it means

The in-memory skills storage `list` method rejects a `page` argument whose resulting offset (`page * perPage`) exceeds `Number.MAX_SAFE_INTEGER / 2`. This guard prevents arithmetic that can no longer be represented exactly as a JS integer and is clearly a caller mistake rather than a storage state issue. The error fires during argument validation before any records are read.

Source

Thrown at packages/core/src/storage/domains/skills/inmemory.ts:235

      visibility,
      metadata,
      entityIds,
      pinFavoritedFor,
      favoritedOnly,
    } = args || {};
    const { field, direction } = this.parseOrderBy(orderBy);

    // Normalize perPage for query (false → MAX_SAFE_INTEGER, 0 → 0, undefined → 100)
    const perPage = normalizePerPage(perPageInput, 100);

    if (page < 0) {
      throw new Error('page must be >= 0');
    }

    // Prevent unreasonably large page values
    const maxOffset = Number.MAX_SAFE_INTEGER / 2;
    if (page * perPage > maxOffset) {
      throw new Error('page value too large');
    }

    // Get all skills and apply filters
    let configs = Array.from(this.db.skills.values());

    // Restrict to a set of IDs (used by ?favoritedOnly=true).
    // An empty array means "no candidates" -> empty result.
    if (entityIds !== undefined) {
      if (entityIds.length === 0) {
        return {
          skills: [],
          total: 0,
          page,
          perPage: perPageInput === false ? false : perPage,
          hasMore: false,
        };
      }
      const idSet = new Set(entityIds);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check the computed page value at the call site; it should be a small sequential index starting at 0.
2. Fix any computation that derives `page` from IDs, timestamps, or byte offsets instead of record counts.
3. Clamp or validate user-supplied page params against a sane maximum before passing to storage.
4. If you truly need all records, pass `perPage: false` (normalizePerPage maps it to MAX_SAFE_INTEGER) with page 0 instead of a giant page number.

Example fix

// before
const page = Number(req.query.page); // e.g. 1e15
await skills.list({ page });
// after
const page = Math.max(0, parseInt(req.query.page, 10) || 0);
if (page > 1e6) throw new BadRequestError('page out of range');
await skills.list({ page });

const MAX_OFFSET = Number.MAX_SAFE_INTEGER / 2;
function assertValidPage(page: number, perPage: number) {
  if (!Number.isInteger(page) || page < 0) throw new RangeError('page must be a non-negative integer');
  if (page * perPage > MAX_OFFSET) throw new RangeError('page value too large');
}

function isSafePage(page: unknown): page is number {
  return typeof page === 'number' && Number.isInteger(page) && page >= 0 && page * 20 <= Number.MAX_SAFE_INTEGER / 2;
}

try {
  const result = await skills.list({ page });
} catch (err) {
  if (err instanceof Error && err.message === 'page value too large') {
    page = 0; // reset to first page and surface a warning
  } else throw err;
}

When it happens

Trigger: Calling `list({ page: <huge number> })` on the in-memory skills storage, where `page * perPage > 9007199254740991 / 2`. Typical sources are multiplying or overflowing a page counter, or passing an ID/string-cast number as page.

Common situations: Pagination cursors computed from data (e.g. using record IDs or timestamps as page numbers), off-by-scale bugs (paginating by milliseconds or bytes instead of pages), or client-supplied query params cast from user input without bounds checking.

Related errors

• page must be >= 0
• page value too large
• page must be >= 0
• perPage must be >= 0
• page must be >= 0

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/ce739ff613b5e8e4. Report an issue: GitHub.