{"record":{"id":"deb677b6c7c52a68","repo":"mastra-ai/mastra","slug":"storage-is-not-configured","errorCode":null,"errorMessage":"Storage is not configured","messagePattern":"Storage is not configured","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/agent-versions.ts","lineNumber":78,"sourceCode":" * GET /stored/agents/:agentId/versions - List all versions for an agent\n */\nexport const LIST_AGENT_VERSIONS_ROUTE = createRoute({\n  method: 'GET',\n  path: '/stored/agents/:agentId/versions',\n  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) {","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/agent-versions.ts#L60-L96","documentation":"The agent-versions list handler requires a configured storage layer: `mastra.getStorage()` returning undefined triggers HTTP 500 'Storage is not configured'. Agent versions are persisted, so version history endpoints cannot function without storage.","triggerScenarios":"Calling agent-version endpoints on a Mastra instance constructed without storage (no `storage:` option / no storage configured in mastra config), or in ephemeral setups where storage was intentionally omitted.","commonSituations":"Fresh projects following quickstart configs without persistence; tests/dev running with in-memory defaults and no storage; misconfigured env vars so the storage constructor is skipped; deploying without adding a storage adapter (LibSQL/Postgres/upstash).","solutions":["Configure storage on your Mastra instance, e.g. `new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) })` (or PostgresStore etc.).","Verify the storage dependency/adapter is installed and the env vars (connection URL) are set.","Confirm the server loads the same Mastra config that includes storage (check mastra.config/entrypoint).","If storage is intentionally absent, avoid agent-version endpoints or feature-flag them in the client."],"exampleFix":"// before\nexport const mastra = new Mastra({ agents: {} });\n// after\nimport { LibSQLStore } from '@mastra/libsql';\nexport const mastra = new Mastra({ agents: {}, storage: new LibSQLStore({ url: process.env.DB_URL ?? 'file:./mastra.db' }) });","handlingStrategy":"validation","validationCode":"import { Mastra } from '@mastra/core';\nconst mastra = getMastra();\nif (!mastra.getStorage()) {\n  throw new Error('Storage must be configured to use agent-version endpoints: new Mastra({ storage: ... })');\n}","typeGuard":"function hasStorage(m: { getStorage(): unknown }): boolean {\n  return m.getStorage() != null;\n}","tryCatchPattern":"try {\n  return await api.listAgentVersions({ agentId });\n} catch (e) {\n  if (isHttpError(e) && e.status === 500 && e.message.includes('Storage is not configured')) {\n    throw new Error('Enable persistence: configure a storage adapter on the Mastra instance');\n  }\n  throw e;\n}","preventionTips":["Always configure a storage adapter (LibSQL/Postgres/etc.) in production deployments.","Assert storage presence in a startup health check.","Feature-flag version-history UI when storage is disabled (e.g. tests)."],"tags":["http-500","storage","configuration","persistence"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}