{"record":{"id":"42693476e7919320","repo":"mastra-ai/mastra","slug":"durable-agent-recover-no-mastra","errorCode":"DURABLE_AGENT_RECOVER_NO_MASTRA","errorMessage":"DurableAgent \"${this.name}\" recover() requires the agent to be registered on a Mastra instance.","messagePattern":"DurableAgent \"(.+?)\" recover\\(\\) requires the agent to be registered on a Mastra instance\\.","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/agent/durable/durable-agent.ts","lineNumber":2335,"sourceCode":"   * `recoverActiveRuns()`.\n   *\n   * @example\n   * ```typescript\n   * const { fullStream, output, cleanup } = await durableAgent.recover(runId, {\n   *   onChunk: chunk => process.stdout.write(chunk.payload?.text ?? ''),\n   * });\n   * for await (const chunk of fullStream) {\n   *   // ...\n   * }\n   * cleanup();\n   * ```\n   */\n  async recover(\n    runId: string,\n    options?: DurableAgentRecoverOptions<TOutput>,\n  ): Promise<DurableAgentStreamResult<TOutput>> {\n    if (!this.#mastra) {\n      throw new MastraError({\n        id: 'DURABLE_AGENT_RECOVER_NO_MASTRA',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text: `DurableAgent \"${this.name}\" recover() requires the agent to be registered on a Mastra instance.`,\n        details: { agentName: this.name, runId },\n      });\n    }\n\n    const workflowsStore = await this.#mastra.getStorage()?.getStore('workflows');\n    if (!workflowsStore) {\n      throw new MastraError({\n        id: 'DURABLE_AGENT_RECOVER_NO_STORAGE',\n        domain: ErrorDomain.AGENT,\n        category: ErrorCategory.USER,\n        text:\n          `DurableAgent \"${this.name}\" recover() requires persistent storage to load the run snapshot. ` +\n          `Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL).`,\n        details: { agentName: this.name, runId },","sourceCodeStart":2317,"sourceCodeEnd":2353,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/agent/durable/durable-agent.ts#L2317-L2353","documentation":"DurableAgent.recover() needs the Mastra instance to load persisted state, leases, and snapshots. If the agent was constructed standalone (not registered via new Mastra({ agents: { ... } }) or mastra.registerAgent), this.#mastra is undefined and MastraError DURABLE_AGENT_RECOVER_NO_MASTRA is thrown (category USER).","triggerScenarios":"Calling recover(runId) on an agent created with `new DurableAgent(...)` but never attached to a Mastra instance; exporting the agent from a file and using it directly instead of via mastra.getAgent(); tests instantiating the agent in isolation.","commonSituations":"Standalone agent usage that works for basic stream() but fails for durable features; forgetting to add the agent to the Mastra agents map after refactoring; unit tests calling recover() on a hand-built agent.","solutions":["Register the agent on a Mastra instance: new Mastra({ agents: { myAgent } }) and call recover via mastra.getAgent('myAgent').","Use mastra.getAgent(name) rather than importing the DurableAgent class instance directly.","In tests, construct a Mastra instance with in-memory/ LibSQL storage before calling recover()."],"exampleFix":"// before\nconst agent = new DurableAgent({ name: 'helper', /* ... */ });\nawait agent.recover(runId); // throws\n// after\nconst mastra = new Mastra({ agents: { helper: agent } });\nawait mastra.getAgent('helper').recover(runId);","handlingStrategy":"validation","validationCode":"if (!mastra.getAgent('helper')) throw new Error('helper agent not registered on Mastra');","typeGuard":null,"tryCatchPattern":"try {\n  await agent.recover(runId);\n} catch (e) {\n  if ((e as any).id === 'DURABLE_AGENT_RECOVER_NO_MASTRA') {\n    // route through mastra.getAgent(...) instead\n  } else throw e;\n}","preventionTips":["Always register DurableAgents in the Mastra agents map.","Access agents via mastra.getAgent(name), never raw imports.","Cover durable methods in integration tests with a real Mastra instance."],"tags":["durable-agent","recover","configuration"],"backgroundTag":"agent-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}