mastra-ai/mastra · error

page must be >= 0

Error message

page must be >= 0

What it means

The in-memory scorer-definitions list() validates that page is non-negative before paginating. Negative pages are meaningless in offset pagination, so the method throws right after normalizing perPage (false -> MAX_SAFE_INTEGER, 0 -> 0, undefined -> 100).

Source

Thrown at packages/core/src/storage/domains/scorer-definitions/inmemory.ts:144

  async list(args?: StorageListScorerDefinitionsInput): Promise<StorageListScorerDefinitionsOutput> {
    const {
      page = 0,
      perPage: perPageInput,
      orderBy,
      authorId,
      organizationId,
      projectId,
      metadata,
      status,
    } = 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 scorer definitions and apply filters
    let scorers = Array.from(this.db.scorerDefinitions.values());

    // Filter by status
    if (status) {
      scorers = scorers.filter(scorer => scorer.status === status);
    }

    // Filter by authorId if provided
    if (authorId !== undefined) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Clamp before calling: Math.max(0, page).
2. Default page to 0 when the value is absent or a sentinel like -1.
3. Use perPage: false (page 0) to list all scorer definitions instead of paging.
4. Validate numeric inputs at the boundary (API handlers, CLI args) before passing them on.

Example fix

// before
await storage.scorerDefinitions.list({ page: prevPage - 1 });
// after
await storage.scorerDefinitions.list({ page: Math.max(0, prevPage - 1) });

function coercePage(p: number | undefined): number {
  const n = p ?? 0;
  if (!Number.isInteger(n) || n < 0) return 0;
  return n;
}

function isNonNegativeInt(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}

try {
  return await storage.scorerDefinitions.list({ page });
} catch (e) {
  if (e instanceof Error && e.message === 'page must be >= 0') {
    return storage.scorerDefinitions.list({ page: 0 });
  }
  throw e;
}

When it happens

Trigger: Calling storage.scorerDefinitions.list({ page: -1 }); passing a computed page like currentIndex - 1 that goes below zero; forwarding an unvalidated negative query param.

Common situations: Off-by-one errors in 'previous page' UI logic; sentinel values of -1 for 'unset'; parsing page from URLs/JSON without clamping.

Related errors

• page value too large
• 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/928bbe2abff7d225. Report an issue: GitHub.