mastra-ai/mastra · critical · Error

Background tasks storage is not available

Error message

Background tasks storage is not available

What it means

After resolving the Mastra storage adapter, getStorage() asks it for the 'backgroundTasks' domain store. If the configured storage class does not implement/expose the backgroundTasks store (older storage version or a storage adapter lacking that domain), the manager throws. Task state cannot be persisted without this store.

Source

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

      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> {
    this.pubsub = pubsub;

    const isProducerOnly = this.config.mode === 'producer';

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade the storage package (e.g. @mastra/libsql, @mastra/pg) to a version that implements the backgroundTasks store, matching your @mastra/core version.
2. Implement the backgroundTasks domain store in your custom storage adapter.
3. Run any provided storage migration/bootstrap (create bg task tables) after upgrading.
4. Swap to an officially supported storage adapter that supports background tasks.

Example fix

// before
const mastra = new Mastra({ storage: oldLibSQLStore }); // no backgroundTasks store
// after
pnpm update @mastra/libsql
const mastra = new Mastra({ storage: new LibSQLStore({ url }) }); // implements backgroundTasks

const storage = mastra.getStorage();
const bgStore = await storage.getStore('backgroundTasks');
if (!bgStore) throw new Error('Storage adapter does not support background tasks — upgrade it');

function supportsBackgroundTasks(s: Storage): boolean {
  return typeof (s as any).getStore === 'function' &&
    ['libsql','pg','upstash','cloud','d1','mongodb'].some(k => s.constructor.name.toLowerCase().includes(k));
}

try {
  await manager.enqueue(payload);
} catch (e) {
  if ((e as Error).message === 'Background tasks storage is not available') {
    throw new Error('Upgrade your @mastra/storage adapter to a version implementing the backgroundTasks store');
  }
  throw e;
}

When it happens

Trigger: Using a custom or legacy storage adapter that has not implemented getStore('backgroundTasks'); a @mastra/core storage version older than the background-tasks feature; passing a partial storage mock in tests.

Common situations: Upgrading @mastra/core without upgrading the storage package (or vice versa); custom DB adapters missing the backgroundTasks tables/domain; third-party community storage adapters predating the feature.

Related errors

• workflowDefinitions storage domain is not available.
• Storage is not initialized
• Memory storage domain is not available on ${this.storage.con
• Skills storage domain is not available
• Scorer definitions storage domain is not available

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