mastra-ai/mastra · critical · Error

Mastra is not registered with this manager

Error message

Mastra is not registered with this manager

What it means

resume() needs the Mastra instance to look up the suspended workflow run and re-drive it. If no Mastra instance was registered on the BackgroundTaskManager (#mastra is undefined), resuming is impossible and the manager throws. This is a wiring/configuration error.

Source

Thrown at packages/core/src/background-tasks/manager.ts:417

      return;
    }
  }

  /**
   * Resume a suspended task. The tool executor must be re-registered via
   * `registerTaskContext(taskId, ...)` before calling this if the original
   * registration is gone (e.g. process restart) — the manager doesn't
   * rehydrate executor closures from storage.
   *
   * `resumeData` is forwarded to the tool's `execute` options on the
   * resumed run.
   */
  async resume(taskId: string, resumeData?: unknown): Promise<BackgroundTask> {
    if (this.shuttingDown) {
      throw new Error('BackgroundTaskManager is shutting down, cannot resume tasks');
    }
    if (!this.#mastra) {
      throw new Error('Mastra is not registered with this manager');
    }

    if (this.initPromise) await this.initPromise;

    const storage = await this.getStorage();
    const task = await storage.getTask(taskId);
    if (!task) {
      throw new Error(`Task not found: ${taskId}`);
    }
    if (task.status !== 'suspended') {
      throw new Error(`Cannot resume task in status '${task.status}' (expected 'suspended')`);
    }

    const canRun = await this.checkConcurrency(task.agentId);
    if (!canRun) {
      // Resume sits outside the queue/fallback-sync paths — there's no
      // synchronous caller to fall back to, and silently leaving the task
      // suspended hides the failure from the caller. Throw and let the

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register Mastra on the manager at construction: `new BackgroundTaskManager(mastra)` or the registration API used in your setup.
2. In scripts/tests, construct Mastra (with storage) and pass it to the manager before resuming.
3. Use the manager instance exposed by the Mastra instance (mastra background task manager accessor) instead of building a new one.
4. Audit manager construction sites for the missing mastra argument.

Example fix

// before
const manager = new BackgroundTaskManager();
await manager.resume(taskId, data); // Mastra is not registered
// after
const mastra = getMastra();
const manager = new BackgroundTaskManager(mastra);
await manager.resume(taskId, data);

const manager = mastra.getBackgroundTaskManager?.() ?? new BackgroundTaskManager(mastra);
if (!managerHasMastra(manager)) throw new Error('Register Mastra before resuming tasks');

function managerHasMastra(m: BackgroundTaskManager): boolean {
  return typeof (m as any).#mastra !== 'undefined' || (m as any)['#mastra'] instanceof Mastra;
} // in practice: construct with mastra so it is always set

try {
  await manager.resume(taskId, data);
} catch (e) {
  if ((e as Error).message === 'Mastra is not registered with this manager') {
    throw new Error('Bug: construct BackgroundTaskManager with the Mastra instance');
  }
  throw e;
}

When it happens

Trigger: Creating BackgroundTaskManager without registering a Mastra instance, then calling resume(); manager constructed manually (e.g. in a script/test) without the mastra reference; a manager obtained via makeLocalManager path lacking registration.

Common situations: Standalone scripts resuming tasks with a hand-built manager; tests constructing the manager without Mastra; refactor where the Mastra registration call was dropped.

Related errors

• list-available-agents requires a Mastra context.
• list-available-tools requires a Mastra context.
• list-available-workflows requires a Mastra context.
• list-workflows requires a Mastra context.
• run-workflow requires a Mastra context.

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