{"record":{"id":"f25fa2a05711815a","repo":"mastra-ai/mastra","slug":"agents-storage-domain-is-not-available-f25fa2","errorCode":null,"errorMessage":"Agents storage domain is not available","messagePattern":"Agents storage domain is not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"critical","filePath":"packages/server/src/server/handlers/stored-agent-favorites.ts","lineNumber":21,"sourceCode":"import { storedAgentIdPathParams } from '../schemas/stored-agents';\nimport { createRoute } from '../server-adapter/routes/route-builder';\nimport { assertStoredResourceScope, getStoredResourceScope } from '../utils';\n\nimport { assertReadAccess, getCallerAuthorId } from './authorship';\nimport { requireBuilderFeature } from './editor-builder';\nimport { handleError } from './error';\n\n/**\n * Resolves the storage and favorites domains, throwing 500 if unavailable.\n */\nasync function getFavoritesContext(mastra: Parameters<typeof requireBuilderFeature>[0]) {\n  const storage = mastra.getStorage();\n  if (!storage) {\n    throw new HTTPException(500, { message: 'Storage is not configured' });\n  }\n  const agentStore = await storage.getStore('agents');\n  if (!agentStore) {\n    throw new HTTPException(500, { message: 'Agents storage domain is not available' });\n  }\n  const favoritesStore = await storage.getStore('favorites');\n  if (!favoritesStore) {\n    throw new HTTPException(500, { message: 'Favorites storage domain is not available' });\n  }\n  return { agentStore, favoritesStore };\n}\n\n/**\n * PUT /stored/agents/:storedAgentId/favorite\n */\nexport const FAVORITE_STORED_AGENT_ROUTE = createRoute({\n  method: 'PUT',\n  path: '/stored/agents/:storedAgentId/favorite',\n  responseType: 'json',\n  pathParamSchema: storedAgentIdPathParams,\n  responseSchema: favoriteToggleResponseSchema,\n  summary: 'Favorite a stored agent',","sourceCodeStart":3,"sourceCodeEnd":39,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-agent-favorites.ts#L3-L39","documentation":"After storage resolves, getFavoritesContext requests the 'agents' storage domain via storage.getStore('agents'). A null/undefined store means the configured storage adapter doesn't provide the agents domain, so the handler throws HTTPException 500. This catches storage adapters that lack agent persistence support.","triggerScenarios":"Hitting a stored-agent favorites endpoint with a storage backend configured but whose getStore('agents') returns null — i.e. an adapter that doesn't implement the agents domain.","commonSituations":"Using a minimal/custom storage adapter missing the agents store; storage adapter version too old to include the agents domain; misconfigured adapter initialized without agent tables/collections.","solutions":["Upgrade or switch to a storage adapter that implements the agents domain","Run the adapter's schema migration/init so agent tables exist","Check the adapter version compatibility with the installed @mastra/core","Verify storage.getStore('agents') directly in a startup health check"],"exampleFix":"// before\nstorage: new MinimalStorage() // no agents domain\n// after\nstorage: new MastraLibSQLStorage({ url: DATABASE_URL }) // full domain support","handlingStrategy":"validation","validationCode":"const storage = mastra.getStorage();\nif (storage && !(await storage.getStore('agents'))) {\n  throw new Error('Storage adapter does not provide the agents domain');\n}","typeGuard":"async function hasAgentsDomain(storage: MastraStorage): Promise<boolean> {\n  return (await storage.getStore('agents')) != null;\n}","tryCatchPattern":"try {\n  await favoritesApi.add(agentId);\n} catch (e) {\n  if (e.status === 500 && /Agents storage domain/.test(e.message)) {\n    reportStorageAdapterIncompatibility();\n  } else throw e;\n}","preventionTips":["Pick storage adapters documented to support all builder domains","Pin adapter and @mastra/core versions together and test upgrades","Verify domain availability in CI with an integration test"],"tags":["storage","storage-domain","http-500"],"backgroundTag":"storage-domain-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}