mastra-ai/mastra · critical · Error

Storage is not initialized

Error message

Storage is not initialized

What it means

BackgroundTaskManager.getStorage() resolves the storage adapter from the registered Mastra instance. If no Mastra instance is registered (or Mastra has no storage configured), there is nowhere to persist task state, so the manager throws instead of silently failing. This is a configuration/lifecycle precondition error.

Source

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

  constructor(config: BackgroundTaskManagerConfig = { enabled: false }) {
    this.config = {
      globalConcurrency: config.globalConcurrency ?? 10,
      perAgentConcurrency: config.perAgentConcurrency ?? 5,
      backpressure: config.backpressure ?? 'queue',
      defaultTimeoutMs: config.defaultTimeoutMs ?? 300_000,
      ...config,
    };
  }

  __registerMastra(mastra: Mastra) {
    this.#mastra = mastra;
  }

  async getStorage() {
    const storage = this.#mastra?.getStorage();
    if (!storage) {
      throw new Error('Storage is not initialized');
    }
    const bgStore = await storage.getStore('backgroundTasks');
    if (!bgStore) {
      throw new Error('Background tasks storage is not available');
    }
    return bgStore;
  }

  async init(pubsub: PubSub): Promise<void> {
    if (this.shuttingDown) {
      throw new Error('BackgroundTaskManager is shutting down, cannot initialize');
    }
    if (this.initPromise) return this.initPromise;
    this.initPromise = this.#doInit(pubsub);
    return this.initPromise;
  }

  async #doInit(pubsub: PubSub): Promise<void> {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a configured Mastra instance (with storage) to the BackgroundTaskManager / ensure `mastra.registerBackgroundTaskManager` (or equivalent) is called.
2. Add `storage: new LibSQLStore(...)` (or your chosen store) to the Mastra constructor options.
3. Await Mastra initialization before invoking manager methods.
4. In tests, construct Mastra with an in-memory/temp storage adapter before creating the manager.

Example fix

// before
const manager = new BackgroundTaskManager();
await manager.enqueue(payload); // Storage is not initialized
// after
const mastra = new Mastra({ storage: new LibSQLStore({ url: process.env.DB_URL }) });
const manager = new BackgroundTaskManager(mastra);
await manager.enqueue(payload);

const storage = mastra?.getStorage?.();
if (!storage) throw new Error('Configure Mastra with a storage adapter before using background tasks');

function hasStorage(m: Mastra | undefined): m is Mastra & { getStorage(): Storage } {
  return !!m && typeof m.getStorage === 'function' && !!m.getStorage();
}

try {
  await manager.enqueue(payload);
} catch (e) {
  if ((e as Error).message === 'Storage is not initialized') {
    throw new Error('App misconfigured: pass `storage` to new Mastra({...})');
  }
  throw e;
}

When it happens

Trigger: Calling any manager operation that needs storage (enqueue, cancel, resume, waitForNextTask) before `new Mastra({ storage })` is passed/registered on the manager; creating a BackgroundTaskManager without a Mastra instance; Mastra instance constructed without a `storage` option.

Common situations: Instantiating a manager standalone in tests without wiring Mastra; forgetting the `storage` field in the Mastra constructor; calling manager APIs during bootstrap before `mastra` registration completes.

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• MastraAuthBetterAuth needs a database to build its own bette
• [Slack] Failed to resolve Mastra storage. Ensure your Mastra
• [Slack] No storage available. SlackProvider requires persist

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