mastra-ai/mastra · error

page must be >= 0

Error message

page must be >= 0

What it means

listEntities validates pagination input before scanning entities: a negative page index cannot be satisfied, so it throws immediately. perPage is normalized separately (default 100). This is a caller-side input validation error.

Source

Thrown at packages/core/src/storage/filesystem-versioned.ts:555

  async deleteEntity(id: string): Promise<void> {
    this.hydrate();
    this.entities.delete(id);
    await this.deleteVersionsByParentId(id);
    this.persistToDisk();
  }

  async listEntities(args: {
    page?: number;
    perPage?: number | false;
    orderBy?: StorageOrderBy;
    filters?: Record<string, unknown>;
    listKey: string;
  }): Promise<Record<string, unknown>> {
    this.hydrate();
    const { page = 0, perPage: perPageInput, orderBy, filters, listKey } = args;

    const perPage = normalizePerPage(perPageInput, 100);
    if (page < 0) throw new Error('page must be >= 0');

    let entities = Array.from(this.entities.values());

    // Apply filters
    if (filters) {
      for (const [key, value] of Object.entries(filters)) {
        if (value === undefined) continue;
        if (key === 'metadata' && typeof value === 'object' && value !== null) {
          entities = entities.filter(e => {
            const meta = (e as Record<string, unknown>)['metadata'] as Record<string, unknown> | undefined;
            if (!meta) return false;
            return Object.entries(value as Record<string, unknown>).every(
              ([k, v]) => JSON.stringify(meta[k]) === JSON.stringify(v),
            );
          });
        } else {
          entities = entities.filter(e => (e as Record<string, unknown>)[key] === value);
        }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Clamp the page value before calling: Math.max(0, page).
2. Initialize page to 0 (the default) rather than -1.
3. Fix the pagination loop so it stops at page 0.

Example fix

// before
const res = await storage.list('agents', { page: page - 1 });
// after
const res = await storage.list('agents', { page: Math.max(0, page - 1) });

if (!Number.isInteger(page) || page < 0) throw new Error('page must be a non-negative integer');

When it happens

Trigger: Calling the storage result/list API with args.page set to a negative number (e.g. a computed page like currentPage - 1 going below 0, or page initialized to -1 as a sentinel).

Common situations: See trigger scenarios.

Related errors

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

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