{"record":{"id":"5a8f9d6b6f6f394c","repo":"mastra-ai/mastra","slug":"background-tasks-storage-is-not-available","errorCode":null,"errorMessage":"Background tasks storage is not available","messagePattern":"Background tasks storage is not available","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/core/src/background-tasks/manager.ts","lineNumber":97,"sourceCode":"      perAgentConcurrency: config.perAgentConcurrency ?? 5,\n      backpressure: config.backpressure ?? 'queue',\n      defaultTimeoutMs: config.defaultTimeoutMs ?? 300_000,\n      ...config,\n    };\n  }\n\n  __registerMastra(mastra: Mastra) {\n    this.#mastra = mastra;\n  }\n\n  async getStorage() {\n    const storage = this.#mastra?.getStorage();\n    if (!storage) {\n      throw new Error('Storage is not initialized');\n    }\n    const bgStore = await storage.getStore('backgroundTasks');\n    if (!bgStore) {\n      throw new Error('Background tasks storage is not available');\n    }\n    return bgStore;\n  }\n\n  async init(pubsub: PubSub): Promise<void> {\n    if (this.shuttingDown) {\n      throw new Error('BackgroundTaskManager is shutting down, cannot initialize');\n    }\n    if (this.initPromise) return this.initPromise;\n    this.initPromise = this.#doInit(pubsub);\n    return this.initPromise;\n  }\n\n  async #doInit(pubsub: PubSub): Promise<void> {\n    this.pubsub = pubsub;\n\n    const isProducerOnly = this.config.mode === 'producer';\n","sourceCodeStart":79,"sourceCodeEnd":115,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/background-tasks/manager.ts#L79-L115","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the storage package (e.g. @mastra/libsql, @mastra/pg) to a version that implements the backgroundTasks store, matching your @mastra/core version.","Implement the backgroundTasks domain store in your custom storage adapter.","Run any provided storage migration/bootstrap (create bg task tables) after upgrading.","Swap to an officially supported storage adapter that supports background tasks."],"exampleFix":"// before\nconst mastra = new Mastra({ storage: oldLibSQLStore }); // no backgroundTasks store\n// after\npnpm update @mastra/libsql\nconst mastra = new Mastra({ storage: new LibSQLStore({ url }) }); // implements backgroundTasks","handlingStrategy":"validation","validationCode":"const storage = mastra.getStorage();\nconst bgStore = await storage.getStore('backgroundTasks');\nif (!bgStore) throw new Error('Storage adapter does not support background tasks — upgrade it');","typeGuard":"function supportsBackgroundTasks(s: Storage): boolean {\n  return typeof (s as any).getStore === 'function' &&\n    ['libsql','pg','upstash','cloud','d1','mongodb'].some(k => s.constructor.name.toLowerCase().includes(k));\n}","tryCatchPattern":"try {\n  await manager.enqueue(payload);\n} catch (e) {\n  if ((e as Error).message === 'Background tasks storage is not available') {\n    throw new Error('Upgrade your @mastra/storage adapter to a version implementing the backgroundTasks store');\n  }\n  throw e;\n}","preventionTips":["Keep @mastra/core and your storage adapter on compatible versions.","Verify the backgroundTasks store exists at startup via getStore('backgroundTasks').","Run storage migrations after upgrading.","Prefer officially supported adapters for background tasks."],"tags":["storage","background-tasks","version-mismatch"],"backgroundTag":"storage-adapter-unsupported","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}