{"record":{"id":"24f5f794e922da1d","repo":"mastra-ai/mastra","slug":"agent-list-suspended-runs-invalid-page","errorCode":"AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE","errorMessage":"Agent \"${this.name}\" listSuspendedRuns() requires page to be a non-negative integer.","messagePattern":"Agent \"(.+?)\" listSuspendedRuns\\(\\) requires page to be a non-negative integer\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":8129,"sourceCode":"   * if (runs[0]) {\n   *   await agent.approveToolCall({ runId: runs[0].runId });\n   * }\n   * ```\n   */\n  async listSuspendedRuns(options: AgentListSuspendedRunsOptions = {}): Promise<AgentListSuspendedRunsResult> {\n    const { threadId, resourceId, fromDate, toDate, perPage, page } = options;\n\n    if (perPage !== undefined && (!Number.isInteger(perPage) || perPage <= 0)) {\n      throw new MastraError({\n        id: 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: `Agent \"${this.name}\" listSuspendedRuns() requires perPage to be a positive integer.`,\n        details: { agentName: this.name, perPage },\n      });\n    }\n    if (page !== undefined && (!Number.isInteger(page) || page < 0)) {\n      throw new MastraError({\n        id: 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: `Agent \"${this.name}\" listSuspendedRuns() requires page to be a non-negative integer.`,\n        details: { agentName: this.name, page },\n      });\n    }\n\n    const effectiveMastra = this.#mastra ?? (await this.#getOrCreateEphemeralMastra());\n    const workflowsStore = await effectiveMastra?.getStorage()?.getStore('workflows');\n\n    if (!workflowsStore) {\n      throw new MastraError({\n        id: 'AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text:\n          `Agent \"${this.name}\" listSuspendedRuns() requires storage to discover suspended runs. ` +","sourceCodeStart":8111,"sourceCodeEnd":8147,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L8111-L8147","documentation":"agent.listSuspendedRuns() requires page, when provided, to be a non-negative integer. Mastra validates this up front and throws AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE, including the agent name and the invalid value in the error details.","triggerScenarios":"Calling agent.listSuspendedRuns({ page: -1 }) or page: 1.5 or page: NaN — commonly from unvalidated query-string input.","commonSituations":"Parsing page from URL params as string/float; zero-based vs one-based confusion leading to negative offsets; arithmetic underflow when computing page = Math.floor(offset/perPage).","solutions":["Pass a non-negative integer (>= 0) for page, or omit it for the first page.","Coerce parsed input: Math.max(0, Math.floor(Number(raw))) with a Number.isInteger guard.","Clamp computed page values before calling the API."],"exampleFix":"// before\nawait agent.listSuspendedRuns({ page: Math.floor(offset / perPage) - 1 });\n// after\nconst page = Math.max(0, Math.floor(offset / perPage) - 1);\nawait agent.listSuspendedRuns({ page });","handlingStrategy":"validation","validationCode":"function isValidPage(v: unknown): v is number {\n  return typeof v === 'number' && Number.isInteger(v) && v >= 0;\n}\nconst opts = isValidPage(rawPage) ? { page: rawPage } : {};","typeGuard":"function isNonNegativeInt(v: unknown): v is number {\n  return Number.isInteger(v) && (v as number) >= 0;\n}","tryCatchPattern":"try {\n  await agent.listSuspendedRuns({ page });\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE') {\n    return agent.listSuspendedRuns();\n  }\n  throw e;\n}","preventionTips":["Clamp computed pages with Math.max(0, Math.floor(n)).","Validate URL params at the boundary before they reach service code.","Document whether page is zero-based in your pagination helpers."],"tags":["agent","validation","pagination","input-validation"],"backgroundTag":"invalid-pagination-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}