{"record":{"id":"63a8b0d4c7990505","repo":"mastra-ai/mastra","slug":"page-must-be-0","errorCode":null,"errorMessage":"page must be >= 0","messagePattern":"page must be >= 0","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/agents/inmemory.ts","lineNumber":139,"sourceCode":"    const {\n      page = 0,\n      perPage: perPageInput,\n      orderBy,\n      authorId,\n      visibility,\n      metadata,\n      status,\n      entityIds,\n      pinFavoritedFor,\n      favoritedOnly,\n    } = args || {};\n    const { field, direction } = this.parseOrderBy(orderBy);\n\n    // Normalize perPage for query (false → MAX_SAFE_INTEGER, 0 → 0, undefined → 100)\n    const perPage = normalizePerPage(perPageInput, 100);\n\n    if (page < 0) {\n      throw new Error('page must be >= 0');\n    }\n\n    // Prevent unreasonably large page values\n    const maxOffset = Number.MAX_SAFE_INTEGER / 2;\n    if (page * perPage > maxOffset) {\n      throw new Error('page value too large');\n    }\n\n    // Get all agents and apply filters\n    let agents = Array.from(this.db.agents.values());\n\n    // Restrict to a set of IDs (used by ?favoritedOnly=true).\n    // An empty array means \"no candidates\" -> empty result.\n    if (entityIds !== undefined) {\n      if (entityIds.length === 0) {\n        return {\n          agents: [],\n          total: 0,","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/agents/inmemory.ts#L121-L157","documentation":"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.","triggerScenarios":"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.","commonSituations":"Decrementing page counters below zero on the first page; uninitialized page variables (undefined arithmetic); passing client-supplied query params straight through without validation.","solutions":["Clamp `page` to `Math.max(0, page)` before calling `list`","Default missing page values to 0 instead of letting arithmetic produce NaN/negatives","Validate client-supplied pagination params at the API boundary"],"exampleFix":"// before\nawait agents.list({ page: currentPage - 1 });\n// after\nawait agents.list({ page: Math.max(0, currentPage - 1) });","handlingStrategy":"validation","validationCode":"const safePage = Number.isFinite(page) && page >= 0 ? Math.floor(page) : 0;\nawait agentsDomain.list({ page: safePage, perPage });","typeGuard":"function isValidPage(page: unknown): page is number {\n  return typeof page === 'number' && Number.isFinite(page) && page >= 0;\n}","tryCatchPattern":"try {\n  return await agentsDomain.list({ page, perPage });\n} catch (e) {\n  if (e instanceof Error && e.message === 'page must be >= 0') {\n    return agentsDomain.list({ page: 0, perPage });\n  }\n  throw e;\n}","preventionTips":["Clamp page with Math.max(0, page) at every call site","Default missing page params to 0","Validate client-supplied pagination at the API boundary","Beware pager UIs that compute currentPage - 1 without a floor"],"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"}