mastra-ai/mastra · error · MastraError

DURABLE_AGENT_RECOVER_NO_MASTRA

DURABLE_AGENT_RECOVER_NO_MASTRA

Error message

DurableAgent "${this.name}" recover() requires the agent to be registered on a Mastra instance.

What it means

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).

Source

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

   * `recoverActiveRuns()`.
   *
   * @example
   * ```typescript
   * const { fullStream, output, cleanup } = await durableAgent.recover(runId, {
   *   onChunk: chunk => process.stdout.write(chunk.payload?.text ?? ''),
   * });
   * for await (const chunk of fullStream) {
   *   // ...
   * }
   * cleanup();
   * ```
   */
  async recover(
    runId: string,
    options?: DurableAgentRecoverOptions<TOutput>,
  ): Promise<DurableAgentStreamResult<TOutput>> {
    if (!this.#mastra) {
      throw new MastraError({
        id: 'DURABLE_AGENT_RECOVER_NO_MASTRA',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: `DurableAgent "${this.name}" recover() requires the agent to be registered on a Mastra instance.`,
        details: { agentName: this.name, runId },
      });
    }

    const workflowsStore = await this.#mastra.getStorage()?.getStore('workflows');
    if (!workflowsStore) {
      throw new MastraError({
        id: 'DURABLE_AGENT_RECOVER_NO_STORAGE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text:
          `DurableAgent "${this.name}" recover() requires persistent storage to load the run snapshot. ` +
          `Register the agent on a Mastra instance with persistent storage (e.g. PostgreSQL, LibSQL).`,
        details: { agentName: this.name, runId },

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the agent on a Mastra instance: new Mastra({ agents: { myAgent } }) and call recover via mastra.getAgent('myAgent').
2. Use mastra.getAgent(name) rather than importing the DurableAgent class instance directly.
3. In tests, construct a Mastra instance with in-memory/ LibSQL storage before calling recover().

Example fix

// before
const agent = new DurableAgent({ name: 'helper', /* ... */ });
await agent.recover(runId); // throws
// after
const mastra = new Mastra({ agents: { helper: agent } });
await mastra.getAgent('helper').recover(runId);

if (!mastra.getAgent('helper')) throw new Error('helper agent not registered on Mastra');

try {
  await agent.recover(runId);
} catch (e) {
  if ((e as any).id === 'DURABLE_AGENT_RECOVER_NO_MASTRA') {
    // route through mastra.getAgent(...) instead
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DURABLE_AGENT_RECOVER_NO_STORAGE
• (result as any).error?.message || 'Workflow recover failed'
• Agent model not available
• No enabled models available for execution
• AcpAgent does not support resuming suspended generate calls

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