mastra-ai/mastra · error · MastraError

AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE

AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE

Error message

Agent "${this.name}" listSuspendedRuns() requires page to be a non-negative integer.

What it means

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.

Source

Thrown at packages/core/src/agent/agent.ts:8129

   * if (runs[0]) {
   *   await agent.approveToolCall({ runId: runs[0].runId });
   * }
   * ```
   */
  async listSuspendedRuns(options: AgentListSuspendedRunsOptions = {}): Promise<AgentListSuspendedRunsResult> {
    const { threadId, resourceId, fromDate, toDate, perPage, page } = options;

    if (perPage !== undefined && (!Number.isInteger(perPage) || perPage <= 0)) {
      throw new MastraError({
        id: 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: `Agent "${this.name}" listSuspendedRuns() requires perPage to be a positive integer.`,
        details: { agentName: this.name, perPage },
      });
    }
    if (page !== undefined && (!Number.isInteger(page) || page < 0)) {
      throw new MastraError({
        id: 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: `Agent "${this.name}" listSuspendedRuns() requires page to be a non-negative integer.`,
        details: { agentName: this.name, page },
      });
    }

    const effectiveMastra = this.#mastra ?? (await this.#getOrCreateEphemeralMastra());
    const workflowsStore = await effectiveMastra?.getStorage()?.getStore('workflows');

    if (!workflowsStore) {
      throw new MastraError({
        id: 'AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text:
          `Agent "${this.name}" listSuspendedRuns() requires storage to discover suspended runs. ` +

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a non-negative integer (>= 0) for page, or omit it for the first page.
2. Coerce parsed input: Math.max(0, Math.floor(Number(raw))) with a Number.isInteger guard.
3. Clamp computed page values before calling the API.

Example fix

// before
await agent.listSuspendedRuns({ page: Math.floor(offset / perPage) - 1 });
// after
const page = Math.max(0, Math.floor(offset / perPage) - 1);
await agent.listSuspendedRuns({ page });

function isValidPage(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v >= 0;
}
const opts = isValidPage(rawPage) ? { page: rawPage } : {};

function isNonNegativeInt(v: unknown): v is number {
  return Number.isInteger(v) && (v as number) >= 0;
}

try {
  await agent.listSuspendedRuns({ page });
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE') {
    return agent.listSuspendedRuns();
  }
  throw e;
}

When it happens

Trigger: Calling agent.listSuspendedRuns({ page: -1 }) or page: 1.5 or page: NaN — commonly from unvalidated query-string input.

Common situations: 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).

Related errors

• AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE
• GitHub cursor must be a positive page number.
• GitHub cursor must be a positive page number.
• AGENT_REQUEST_CONTEXT_VALIDATION_FAILED
• Either message or messages must be provided

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