mastra-ai/mastra · error · MastraError

DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PAGE

DURABLE_AGENT_LIST_ACTIVE_RUNS_INVALID_PAGE

Error message

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

What it means

DurableAgent.listActiveRuns() validates pagination arguments before querying storage. The `page` parameter, when provided, must be a non-negative integer (0-based page index). A negative number, NaN, or a non-integer like 1.5 triggers this MastraError with ErrorCategory.USER.

Source

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

   * 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');

    if (!workflowsStore) {
      throw new MastraError({
        id: 'DURABLE_AGENT_LIST_ACTIVE_RUNS_NO_STORAGE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text:
          `DurableAgent "${this.name}" listActiveRuns() requires storage to discover running runs. ` +
          `Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage`,

View on GitHub (pinned to 75dd419e61)

Solutions

Pass a non-negative integer for page (0 is valid, the first page).
Omit `page` entirely if you only want the default first page.
Sanitize values derived from user input: Number.isInteger(page) && page >= 0 before calling.

Example fix

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

Defensive patterns

Strategy: validation

Validate before calling

function isValidPage(page: unknown): page is number {
  return page === undefined || (Number.isInteger(page) && page >= 0);
}
if (!isValidPage(page)) throw new TypeError('page must be a non-negative integer');
await agent.listActiveRuns({ page, perPage });

Type guard

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

Prevention

Coerce pagination from user input with Math.max(0, Math.floor(Number(page)))
Omit `page` when you want the first page instead of passing 1-based or computed values
Wrap pagination params in a shared sanitize helper used by all list calls

When it happens

Trigger: Calling listActiveRuns({ page }) where page is negative (e.g. -1), a float (e.g. 1.5), or otherwise not an integer (e.g. NaN from parsed input). Only raised when page !== undefined.

Common situations: Computing page indexes with off-by-one subtraction (page-1 on page 0), parsing user query params with parseFloat, or passing undefined-derived NaN values from spreadsheet/CLI tooling.

Related errors

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