mastra-ai/mastra · error · MastraError

AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE

AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE

Error message

Agent "${this.name}" listSuspendedRuns() requires storage to discover suspended runs. Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage

What it means

listSuspendedRuns() discovers suspended workflow runs through the workflows storage store. If the agent's Mastra instance has no storage configured (or no workflows store is available), Mastra throws AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE telling you to attach persistent storage. Suspending runs requires durable state, so this API simply cannot work without it.

Source

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

        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. ` +
          `Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage`,
        details: { agentName: this.name },
      });
    }

    // resourceId is a storage column, so push it down to narrow the query;
    // threadId lives inside the snapshot state, so fetch matching rows and
    // filter/paginate here to keep `total` accurate. The in-process resource
    // check below stays as the correctness backstop: adapters silently skip
    // the filter when the column is missing, and rows persisted before the
    // column was populated carry the resource only in the snapshot. Durable
    // agents persist their agentic loop under a separate workflow name, so
    // query both — otherwise suspended durable runs are never discoverable.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure persistent storage on the Mastra instance: new Mastra({ storage: new PostgresStore(...) }) (or LibSQL, etc.).
2. Ensure the agent is registered on that Mastra instance (via `new Mastra({ agents: { myAgent } })`) rather than used standalone.
3. Verify the storage backend exposes the workflows store (getStore('workflows')).

Example fix

// before
const mastra = new Mastra({ agents: { myAgent } });
await myAgent.listSuspendedRuns();
// after
const mastra = new Mastra({ agents: { myAgent }, storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }) });
await myAgent.listSuspendedRuns();

const store = await mastra.getStorage()?.getStore('workflows');
if (!store) {
  throw new Error('listSuspendedRuns requires persistent storage; configure Mastra storage first');
}

try {
  return await agent.listSuspendedRuns(opts);
} catch (e) {
  if (e instanceof MastraError && e.id === 'AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE') {
    logger.warn('No storage configured; suspended run listing unavailable');
    return { runs: [], total: 0 };
  }
  throw e;
}

When it happens

Trigger: Calling agent.listSuspendedRuns() on an agent whose Mastra instance was constructed without a storage option, or where getStorage()?.getStore('workflows') returns undefined (in-memory/default Mastra).

Common situations: Dev setups using ephemeral Mastra instances; forgetting to pass storage to `new Mastra({...})`; using a storage backend that doesn't provide the workflows domain; calling in unit tests where storage was omitted.

Related errors

• sendNotificationSignal requires a notifications storage doma
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• MastraAuthBetterAuth needs a database to build its own bette
• [Slack] Failed to resolve Mastra storage. Ensure your Mastra

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