{"record":{"id":"b8dff0a736f99240","repo":"mastra-ai/mastra","slug":"agent-list-suspended-runs-invalid-per-page","errorCode":"AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE","errorMessage":"Agent \"${this.name}\" listSuspendedRuns() requires perPage to be a positive integer.","messagePattern":"Agent \"(.+?)\" listSuspendedRuns\\(\\) requires perPage to be a positive integer\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":8120,"sourceCode":"   * `approveToolCall()`, or `declineToolCall()`.\n   *\n   * Results are scoped to runs started by this agent: snapshots persist the owning\n   * agent's id, and runs whose snapshots carry a different id are skipped. Filter by\n   * `threadId`/`resourceId` to scope results to a conversation.\n   *\n   * @example\n   * ```typescript\n   * const { runs } = await agent.listSuspendedRuns({ threadId, resourceId });\n   * 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());","sourceCodeStart":8102,"sourceCodeEnd":8138,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L8102-L8138","documentation":"agent.listSuspendedRuns() validates its pagination options before querying storage. If perPage is provided but is not a positive integer (non-integer, zero, or negative), Mastra throws AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE immediately with the agent name and offending value in details.","triggerScenarios":"Calling agent.listSuspendedRuns({ perPage: 0 }) or perPage: -10, perPage: 2.5, or perPage: NaN (e.g. derived from parsed query params without validation).","commonSituations":"Passing URL query string values parsed as strings or floats into perPage; computing page size from user input; defaulting with 0 to mean 'no limit'.","solutions":["Pass a positive integer (>= 1) for perPage, or omit it to use the default.","Coerce and validate user-supplied values before calling: Number.isInteger(v) && v > 0.","If you intended 'no limit', drop perPage rather than passing 0."],"exampleFix":"// before\nawait agent.listSuspendedRuns({ perPage: Number(searchParams.get('perPage')) });\n// after\nconst perPage = Number(searchParams.get('perPage'));\nawait agent.listSuspendedRuns(perPage > 0 && Number.isInteger(perPage) ? { perPage } : {});","handlingStrategy":"validation","validationCode":"function isValidPerPage(v: unknown): v is number {\n  return typeof v === 'number' && Number.isInteger(v) && v > 0;\n}\nconst opts = isValidPerPage(rawPerPage) ? { perPage: rawPerPage } : {};","typeGuard":"function isPositiveInt(v: unknown): v is number {\n  return Number.isInteger(v) && (v as number) > 0;\n}","tryCatchPattern":"try {\n  await agent.listSuspendedRuns({ perPage });\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE') {\n    return agent.listSuspendedRuns(); // fall back to defaults\n  }\n  throw e;\n}","preventionTips":["Coerce and clamp query-string params before passing pagination options.","Use zod or similar to validate options objects at API boundaries.","Treat 'all results' as omitting perPage, not perPage: 0."],"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"}