mastra-ai/mastra · error

page value too large

Error message

page value too large

What it means

list() also guards against absurd page values whose byte/page offset (page * perPage) would exceed Number.MAX_SAFE_INTEGER / 2. Such offsets can't be meaningfully represented when slicing arrays, so the domain throws rather than returning corrupted or silently empty results.

Source

Thrown at packages/core/src/storage/domains/workspaces/inmemory.ts:209

    // Also delete all versions for this workspace
    await this.deleteVersionsByParentId(id);
  }

  async list(args?: StorageListWorkspacesInput): Promise<StorageListWorkspacesOutput> {
    const { page = 0, perPage: perPageInput, orderBy, authorId, metadata } = 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 workspaces and apply filters
    let configs = Array.from(this.db.workspaces.values());

    // Filter by authorId if provided
    if (authorId !== undefined) {
      configs = configs.filter(config => config.authorId === authorId);
    }

    // Filter by metadata if provided (AND logic)
    if (metadata && Object.keys(metadata).length > 0) {
      configs = configs.filter(config => {
        if (!config.metadata) return false;
        return Object.entries(metadata).every(([key, value]) => deepEqual(config.metadata![key], value));
      });
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use page: 0 whenever you pass perPage: false for a fetch-all query
2. Cap page values to a sane maximum in your pagination layer
3. Compute offset once and assert Number.isSafeInteger(offset) before calling list
4. If you truly need deep pagination, iterate pages incrementally instead of jumping to a huge page

Example fix

// before
const res = await storage.workspaces.list({ page: deepPage, perPage: false }); // offset overflows
// after
const res = deepPage > 0
  ? await storage.workspaces.list({ page: deepPage })
  : await storage.workspaces.list({ page: 0, perPage: false });

const MAX_OFFSET = Number.MAX_SAFE_INTEGER / 2;
if (page * perPage > MAX_OFFSET) throw new RangeError('page value too large');

function isSafePage(page: number, perPage: number): boolean {
  return Number.isInteger(page) && page >= 0 && page * perPage <= Number.MAX_SAFE_INTEGER / 2;
}

try {
  return await storage.workspaces.list({ page, perPage });
} catch (err) {
  if (err instanceof Error && err.message === 'page value too large') {
    // fall back to first page and log the bad request
    return await storage.workspaces.list({ page: 0, perPage });
  }
  throw err;
}

When it happens

Trigger: Passing extremely large page numbers (e.g. page: Number.MAX_SAFE_INTEGER) even with default perPage; passing perPage: false (which normalizes to MAX_SAFE_INTEGER) together with any page > ~0 — page 1 * MAX_SAFE_INTEGER already exceeds the cap; multiplying page in a loop that escapes bounds.

Common situations: Using 'unbounded fetch' perPage: false while still sending page > 0 from a UI; fuzz/property tests with huge integers; integer overflow in page arithmetic before the call.

Related errors

• page must be >= 0
• perPage must be >= 0
• page must be >= 0
• page value too large
• Invalid knowledge node cursor.

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