mastra-ai/mastra · error · Error

page must be >= 0

Error message

page must be >= 0

What it means

The agents `list` method validates pagination inputs: `page` must be a non-negative number. Negative page values would produce invalid offsets, so the method throws instead.

Source

Thrown at packages/core/src/storage/domains/agents/inmemory.ts:139

    const {
      page = 0,
      perPage: perPageInput,
      orderBy,
      authorId,
      visibility,
      metadata,
      status,
      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 agents and apply filters
    let agents = Array.from(this.db.agents.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 {
          agents: [],
          total: 0,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Clamp `page` to `Math.max(0, page)` before calling `list`
2. Default missing page values to 0 instead of letting arithmetic produce NaN/negatives
3. Validate client-supplied pagination params at the API boundary

Example fix

// before
await agents.list({ page: currentPage - 1 });
// after
await agents.list({ page: Math.max(0, currentPage - 1) });

const safePage = Number.isFinite(page) && page >= 0 ? Math.floor(page) : 0;
await agentsDomain.list({ page: safePage, perPage });

function isValidPage(page: unknown): page is number {
  return typeof page === 'number' && Number.isFinite(page) && page >= 0;
}

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

When it happens

Trigger: Calling `list({ page: -1 })` (or any negative page), often from a UI pager that computes `currentPage - 1` without clamping at 0, or NaN-adjacent math producing negatives.

Common situations: Decrementing page counters below zero on the first page; uninitialized page variables (undefined arithmetic); passing client-supplied query params straight through without validation.

Related errors

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

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