{"record":{"id":"3048e77ac241075a","repo":"mastra-ai/mastra","slug":"agent-list-suspended-runs-no-storage","errorCode":"AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE","errorMessage":"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","messagePattern":"Agent \"(.+?)\" 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","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/agent.ts","lineNumber":8142,"sourceCode":"        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());\n    const workflowsStore = await effectiveMastra?.getStorage()?.getStore('workflows');\n\n    if (!workflowsStore) {\n      throw new MastraError({\n        id: 'AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text:\n          `Agent \"${this.name}\" listSuspendedRuns() requires storage to discover suspended runs. ` +\n          `Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL). See https://mastra.ai/docs/storage`,\n        details: { agentName: this.name },\n      });\n    }\n\n    // resourceId is a storage column, so push it down to narrow the query;\n    // threadId lives inside the snapshot state, so fetch matching rows and\n    // filter/paginate here to keep `total` accurate. The in-process resource\n    // check below stays as the correctness backstop: adapters silently skip\n    // the filter when the column is missing, and rows persisted before the\n    // column was populated carry the resource only in the snapshot. Durable\n    // agents persist their agentic loop under a separate workflow name, so\n    // query both — otherwise suspended durable runs are never discoverable.","sourceCodeStart":8124,"sourceCodeEnd":8160,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/agent.ts#L8124-L8160","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Configure persistent storage on the Mastra instance: new Mastra({ storage: new PostgresStore(...) }) (or LibSQL, etc.).","Ensure the agent is registered on that Mastra instance (via `new Mastra({ agents: { myAgent } })`) rather than used standalone.","Verify the storage backend exposes the workflows store (getStore('workflows'))."],"exampleFix":"// before\nconst mastra = new Mastra({ agents: { myAgent } });\nawait myAgent.listSuspendedRuns();\n// after\nconst mastra = new Mastra({ agents: { myAgent }, storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }) });\nawait myAgent.listSuspendedRuns();","handlingStrategy":"validation","validationCode":"const store = await mastra.getStorage()?.getStore('workflows');\nif (!store) {\n  throw new Error('listSuspendedRuns requires persistent storage; configure Mastra storage first');\n}","typeGuard":null,"tryCatchPattern":"try {\n  return await agent.listSuspendedRuns(opts);\n} catch (e) {\n  if (e instanceof MastraError && e.id === 'AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE') {\n    logger.warn('No storage configured; suspended run listing unavailable');\n    return { runs: [], total: 0 };\n  }\n  throw e;\n}","preventionTips":["Always configure storage (Postgres/LibSQL) on Mastra instances in production.","Assert storage availability in app startup/health checks.","Verify the storage adapter supports the workflows domain before using suspend/resume features."],"tags":["agent","storage","configuration","suspended-runs"],"backgroundTag":"missing-storage-configuration","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}