{"record":{"id":"7569d36582f8f2cd","repo":"mastra-ai/mastra","slug":"agents-storage-domain-is-not-available","errorCode":null,"errorMessage":"Agents storage domain is not available","messagePattern":"Agents storage domain is not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/agent-versions.ts","lineNumber":83,"sourceCode":"  requiresAuth: true,\n  responseType: 'json',\n  pathParamSchema: agentVersionPathParams,\n  queryParamSchema: listVersionsQuerySchema,\n  responseSchema: listVersionsResponseSchema,\n  summary: 'List agent versions',\n  description: 'Returns a paginated list of all versions for a stored agent',\n  tags: ['Agent Versions'],\n  handler: async ({ mastra, agentId, page, perPage, orderBy, requestContext }) => {\n    try {\n      const storage = mastra.getStorage();\n\n      if (!storage) {\n        throw new HTTPException(500, { message: 'Storage is not configured' });\n      }\n\n      const agentsStore = await storage.getStore('agents');\n      if (!agentsStore) {\n        throw new HTTPException(500, { message: 'Agents storage domain is not available' });\n      }\n\n      // Verify agent exists in code or storage\n      const storedAgent = await agentsStore.getById(agentId);\n      let codeAgentExists = false;\n      try {\n        mastra.getAgentById(agentId);\n        codeAgentExists = true;\n      } catch {\n        // Agent not registered in code\n      }\n\n      if (!storedAgent && !codeAgentExists) {\n        throw new HTTPException(404, { message: `Agent with id ${agentId} not found` });\n      }\n      assertStoredResourceScope(storedAgent, await getStoredResourceScope(mastra, requestContext));\n\n      const result = await agentsStore.listVersions({","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agent-versions.ts#L65-L101","documentation":"This 500 is thrown by the LIST_AGENT_VERSIONS route (GET /stored/agents/:agentId/versions) when Mastra storage is configured, but storage.getStore('agents') returns no agents domain store. It means the configured storage adapter does not implement (or failed to initialize) the 'agents' store domain, so agent versions cannot be listed.","triggerScenarios":"Calling the list-agent-versions API against a Mastra instance whose storage adapter lacks an agents domain, or whose getStore('agents') initialization returns null/undefined at request time.","commonSituations":"Using a custom or legacy storage adapter that only implements some domains (e.g. traces or workflows) but not agents; storage configured without agent-versioning support; a partially-failed storage initialization after a dependency or adapter upgrade.","solutions":["Configure a full storage adapter (e.g. @mastra/libsql, @mastra/pg, @mastra/upstash) that implements the agents domain","Verify the storage adapter version supports agent versioning (getStore('agents')) and upgrade it if not","Check storage initialization logs/errors for why the agents domain store failed to load","If agents storage is intentionally absent, stop calling the /stored/agents/:agentId/versions endpoints"],"exampleFix":"// before\nnew Mastra({ storage: new PartialStorageAdapter({ traces: true }) });\n// after\nimport { LibSQLStore } from '@mastra/libsql';\nnew Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) });","handlingStrategy":"validation","validationCode":"const storage = mastra.getStorage();\nif (!storage) throw new Error('Mastra storage is not configured');\nconst agentsStore = await storage.getStore('agents');\nif (!agentsStore) throw new Error('Storage adapter lacks an agents domain; use a full adapter like LibSQLStore/PgStore');","typeGuard":"function hasAgentsStore(s: unknown): s is { getStore: (d: 'agents') => Promise<unknown> } {\n  return !!s && typeof (s as any).getStore === 'function';\n}","tryCatchPattern":"try {\n  const res = await fetch(`/api/stored/agents/${agentId}/versions`);\n  if (res.status === 500) {\n    const body = await res.json();\n    if (String(body.message).includes('storage')) throw new Error('Server storage misconfigured — configure a full storage adapter');\n  }\n} catch (e) { /* surface config error to operator */ }","preventionTips":["Always configure a storage adapter that implements all required domains","Smoke-test storage.getStore('agents') at server startup and fail fast","Pin storage adapter versions known to support agent versioning","Log storage initialization failures prominently"],"tags":["storage","server","agent-versions","configuration"],"backgroundTag":"storage-domain-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}