{"record":{"id":"6c8c93767cca07f5","repo":"mastra-ai/mastra","slug":"page-must-be-0-6c8c93","errorCode":null,"errorMessage":"page must be >= 0","messagePattern":"page must be >= 0","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/filesystem-versioned.ts","lineNumber":555,"sourceCode":"  async deleteEntity(id: string): Promise<void> {\n    this.hydrate();\n    this.entities.delete(id);\n    await this.deleteVersionsByParentId(id);\n    this.persistToDisk();\n  }\n\n  async listEntities(args: {\n    page?: number;\n    perPage?: number | false;\n    orderBy?: StorageOrderBy;\n    filters?: Record<string, unknown>;\n    listKey: string;\n  }): Promise<Record<string, unknown>> {\n    this.hydrate();\n    const { page = 0, perPage: perPageInput, orderBy, filters, listKey } = args;\n\n    const perPage = normalizePerPage(perPageInput, 100);\n    if (page < 0) throw new Error('page must be >= 0');\n\n    let entities = Array.from(this.entities.values());\n\n    // Apply filters\n    if (filters) {\n      for (const [key, value] of Object.entries(filters)) {\n        if (value === undefined) continue;\n        if (key === 'metadata' && typeof value === 'object' && value !== null) {\n          entities = entities.filter(e => {\n            const meta = (e as Record<string, unknown>)['metadata'] as Record<string, unknown> | undefined;\n            if (!meta) return false;\n            return Object.entries(value as Record<string, unknown>).every(\n              ([k, v]) => JSON.stringify(meta[k]) === JSON.stringify(v),\n            );\n          });\n        } else {\n          entities = entities.filter(e => (e as Record<string, unknown>)[key] === value);\n        }","sourceCodeStart":537,"sourceCodeEnd":573,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/filesystem-versioned.ts#L537-L573","documentation":"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.","triggerScenarios":"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).","commonSituations":"See trigger scenarios.","solutions":["Clamp the page value before calling: Math.max(0, page).","Initialize page to 0 (the default) rather than -1.","Fix the pagination loop so it stops at page 0."],"exampleFix":"// before\nconst res = await storage.list('agents', { page: page - 1 });\n// after\nconst res = await storage.list('agents', { page: Math.max(0, page - 1) });","handlingStrategy":"validation","validationCode":"if (!Number.isInteger(page) || page < 0) throw new Error('page must be a non-negative integer');","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default page to 0 and clamp computed pages with Math.max(0, page).","Never use -1 as a page sentinel; use null/undefined to mean 'first page'.","Centralize pagination input normalization in one helper."],"tags":["storage","pagination","validation"],"backgroundTag":"invalid-pagination-parameters","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}