mastra-ai/mastra · error

page value too large

Error message

page value too large

What it means

When computing offset = page * perPage, the result must remain a safe integer (within Number.MAX_SAFE_INTEGER). Extremely large page or perPage values would overflow and produce incorrect offsets, so the library throws 'page value too large' instead.

Source

Thrown at packages/core/src/storage/domains/memory/base.ts:470

  protected validatePagination(page: number, perPage: number): void {
    if (!Number.isFinite(page) || !Number.isSafeInteger(page) || page < 0) {
      throw new Error('page must be >= 0');
    }

    // perPage: 0 is allowed (returns empty results), negative values are rejected
    if (!Number.isFinite(perPage) || !Number.isSafeInteger(perPage) || perPage < 0) {
      throw new Error('perPage must be >= 0');
    }

    // Skip overflow check when perPage is 0 (no offset needed)
    if (perPage === 0) {
      return;
    }

    // Prevent overflow when calculating offset
    const offset = page * perPage;
    if (!Number.isSafeInteger(offset) || offset > Number.MAX_SAFE_INTEGER) {
      throw new Error('page value too large');
    }
  }

  /**
   * Validates pagination input before normalization.
   * Use this when accepting raw perPageInput (number | false) from callers.
   *
   * When perPage is false (fetch all), page must be 0 since pagination is disabled.
   * When perPage is a number, delegates to validatePagination for full validation.
   *
   * @param page - Page number (0-indexed)
   * @param perPageInput - Items per page as number, or false to fetch all results
   * @throws Error if perPageInput is false and page !== 0
   * @throws Error if perPageInput is invalid (not false or a non-negative safe integer)
   * @throws Error if page is invalid or offset would overflow
   */
  protected validatePaginationInput(page: number, perPageInput: number | false): void {
    // Validate perPageInput type first

View on GitHub (pinned to 75dd419e61)

Solutions

1. Cap the page value against a sane maximum before calling (e.g. if (page > 1e6) reject).
2. Compute total record counts first and clamp page to the last valid page.
3. Validate Number.isSafeInteger(page * perPage) client-side before the call.
4. Treat the error as a bad request (400) in API layers rather than retrying.

Example fix

// before
const page = Number(req.query.page); // user sent 1e15
await storage.listThreads({ page, perPage: 100 });
// after
const page = Math.min(Number(req.query.page) || 0, 1_000_000);
await storage.listThreads({ page, perPage: 100 });

function assertSafeOffset(page, perPage) {
  if (!Number.isSafeInteger(page * perPage)) {
    throw new Error('page value too large');
  }
}

function hasSafeOffset(page: number, perPage: number): boolean {
  return Number.isSafeInteger(page * perPage);
}

try {
  await storage.listThreads({ page, perPage });
} catch (e) {
  if (e instanceof Error && e.message === 'page value too large') {
    return { resources: [], total: 0 }; // treat as out-of-range page
  }
  throw e;
}

When it happens

Trigger: Calling listThreads/listMessages with huge values such as { page: 1e15, perPage: 100 } or { page: Number.MAX_SAFE_INTEGER, perPage: 2 }, where page * perPage exceeds Number.MAX_SAFE_INTEGER.

Common situations: Unbounded user-supplied page query params passed straight through; retry loops incrementing page forever; client bugs sending Infinity or astronomical page numbers.

Related errors

• GitHub cursor must be a positive page number.
• GitHub cursor must be a positive page number.
• AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE
• AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE
• DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PER_PAGE

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