mastra-ai/mastra · warning · MastraError

DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PER_PAGE

DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PER_PAGE

Error message

DurableAgent "${this.name}" listActiveRuns() requires perPage to be a positive integer.

What it means

listActiveRuns() validates its pagination options: if perPage is provided it must be a positive integer. Otherwise MastraError DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PER_PAGE (category USER) is thrown at durable-agent.ts:2903. Omitting perPage entirely is allowed.

Source

Thrown at packages/core/src/agent/durable/durable-agent.ts:2903

   * (see {@link DurableAgent.recoverActiveRuns} and workflow `restart`).
   *
   * Requires persistent workflow storage. Filters `agentId` against the
   * persisted `DurableAgenticWorkflowInput.agentId`, so runs started by other
   * durable agents sharing the same storage are not surfaced.
   *
   * @example
   * ```typescript
   * const { runs } = await durableAgent.listActiveRuns({ resourceId });
   * for (const run of runs) {
   *   await durableAgent.recoverActiveRuns({ runId: run.runId });
   * }
   * ```
   */
  async listActiveRuns(options: DurableAgentListActiveRunsOptions = {}): Promise<DurableAgentListActiveRunsResult> {
    const { threadId, resourceId, fromDate, toDate, perPage, page } = options;

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

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Coerce and validate before calling: Number.isInteger(perPage) && perPage > 0, otherwise omit the option or clamp to a sane default.
2. Parse query-string values with Number()/parseInt before passing them.
3. Treat 0/negative as 'use the default' by omitting perPage instead of sending it.
4. Floor any computed page-size values (Math.floor) so floats never reach the API.

Example fix

// before
await agent.listActiveRuns({ perPage: req.query.perPage }); // string -> throws
// after
const perPage = Number(req.query.perPage);
await agent.listActiveRuns(Number.isInteger(perPage) && perPage > 0 ? { perPage } : {});

function normalizePerPage(v: unknown): number | undefined {
  const n = Number(v);
  return Number.isInteger(n) && n > 0 ? n : undefined;
}
const perPage = normalizePerPage(req.query.perPage);

function isValidPerPage(v: unknown): v is number {
  return typeof v === 'number' && Number.isInteger(v) && v > 0;
}

try {
  await agent.listActiveRuns(opts);
} catch (e) {
  if ((e as any).id === 'DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PER_PAGE') {
    // fall back to default pagination
    return agent.listActiveRuns();
  } else throw e;
}

When it happens

Trigger: Passing perPage: 0, a negative number, a float like 10.5, NaN, or a string from a query param; deriving perPage from user input without parsing; computing perPage via arithmetic that yields a non-integer.

Common situations: Reading perPage from req.query (?perPage=20) and passing the string through; UI sending perPage=0 for 'show all'; off-by-one arithmetic producing 0 on the first page; JSON payloads with null coerced unexpectedly.

Related errors

• GitHub cursor must be a positive page number.
• GitHub cursor must be a positive page number.
• AGENT_LIST_SUSPENDED_RUNS_INVALID_PER_PAGE
• AGENT_LIST_SUSPENDED_RUNS_INVALID_PAGE
• resumeStream() on DurableAgent requires a runId in streamOpt

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