mastra-ai/mastra · error · MastraError

AGENT_DURABLE_METHOD_NOT_AVAILABLE

AGENT_DURABLE_METHOD_NOT_AVAILABLE

Error message

Agent.${method}() is only available on agents constructed with `durable: true`. Configure `new Agent({ durable: true })` or retrieve the durable agent from a registered Mastra instance.

What it means

#requireStandaloneDurable(method) resolves the agent's standalone durable wrapper (created when the Agent is constructed with durable: true). If the agent is not durable, calling durable-only methods such as recover()/workflowInput() throws this USER error. It is a configuration problem, not a runtime failure.

Source

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

  // execution. Each delegator resolves the lazily-built standalone
  // `DurableAgent` wrapper via `#getStandaloneDurable()` and forwards the call.
  //
  // On a non-durable agent they throw `AGENT_DURABLE_METHOD_NOT_AVAILABLE` so
  // callers get a clear error instead of a confusing "not a function" from a
  // typo-safe method that silently does nothing.
  //
  // When the agent is attached to a `Mastra`, Mastra auto-wraps at
  // registration and the caller already holds a `DurableAgent`, so the base
  // methods below are unreachable via the wrapper — `#getStandaloneDurable()`
  // returns `undefined` and the throw path fires. To avoid that misleading
  // error, callers should either use the wrapper Mastra hands back or omit the
  // `Mastra` registration and rely on the standalone wrapper.
  // ---------------------------------------------------------------------------

  async #requireStandaloneDurable(method: string): Promise<StandaloneDurableWrapper> {
    const durable = await this.#getStandaloneDurable();
    if (!durable) {
      throw new MastraError({
        id: 'AGENT_DURABLE_METHOD_NOT_AVAILABLE',
        domain: ErrorDomain.AGENT,
        category: ErrorCategory.USER,
        text: `Agent.${method}() is only available on agents constructed with \`durable: true\`. Configure \`new Agent({ durable: true })\` or retrieve the durable agent from a registered Mastra instance.`,
        details: { agentId: this.id, method },
      });
    }
    return durable;
  }

  /** Resume a suspended durable run. Only valid when `durable: true`. */
  async resume(
    runId: string,
    resumeData: unknown,
    options?: DurableAgentStreamOptions<TOutput>,
  ): Promise<DurableAgentStreamResult<TOutput>> {
    const durable = await this.#requireStandaloneDurable('resume');
    return durable.resume(runId, resumeData, options) as Promise<DurableAgentStreamResult<TOutput>>;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Construct the agent with durable: true: new Agent({ ..., durable: true }).
2. Alternatively, register the agent in a Mastra instance and retrieve it via mastra.getAgent('id') so the durable wrapper is available.
3. If durability is not intended, replace the durable-only call with the non-durable equivalent (e.g. resume via sendStreamResume).

Example fix

// before
const agent = new Agent({ name: 'helper', instructions, model });
await agent.recover(runId); // throws
// after
const agent = new Agent({ name: 'helper', instructions, model, durable: true });
await agent.recover(runId);

if (!agentIsDurable(agent)) { // e.g. constructed without durable: true
  throw new Error('recover() requires new Agent({ durable: true }) or a Mastra-registered durable agent.');
}

function isDurableAgent(a: unknown): a is { recover: (runId: string) => Promise<unknown> } {
  return typeof a === 'object' && a !== null && 'recover' in a && typeof (a as any).recover === 'function';
}

When it happens

Trigger: Calling any durable-only method (e.g. agent.recover(runId), agent.workflowInput(...)) on an agent constructed without `durable: true` in new Agent({...}), or on an agent not retrieved from a registered Mastra instance that provides durability.

Common situations: Copy-pasting durable-agent sample code onto an existing plain Agent; forgetting the durable flag during migration to durable agents; calling recover() on an agent instantiated standalone rather than via mastra.getAgent(); version upgrade where durable APIs were adopted but constructor options were not updated.

Related errors

• AGENT_GENEREATE_SCORER_NOT_FOUND
• AGENT_LIST_SUSPENDED_RUNS_NO_STORAGE
• sendNotificationSignal requires a notifications storage doma
• AGENT_SEND_TOOL_APPROVAL_AMBIGUOUS_SUSPENDED_RUNS
• AGENT_SEND_TOOL_APPROVAL_NO_ACTIVE_THREAD_RUN

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