{"record":{"id":"105dd33489ab43d6","repo":"mastra-ai/mastra","slug":"agents-storage-domain-is-not-available-105dd3","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-agents.ts","lineNumber":260,"sourceCode":"    perPage,\n    orderBy,\n    status,\n    authorId,\n    visibility,\n    metadata,\n    favoritedOnly,\n    pinFavoritedFor,\n  }) => {\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      // Resolve the visibility scope for this caller. Non-owner queries for\n      // another author return only that author's public rows; default lists\n      // return the caller's rows plus legacy unowned records.\n      const filter = resolveAuthorFilter({\n        requestContext,\n        resource: 'stored-agents',\n        queryAuthorId: authorId,\n        queryVisibility: visibility === 'public' ? 'public' : undefined,\n      });\n\n      const scope = await getStoredResourceScope(mastra, requestContext);\n      const scopedMetadata = scopeStoredResourceMetadata(metadata, scope);\n\n      const callerId = getCallerAuthorId(requestContext);\n      const favoritesEnabled = await isBuilderFeatureEnabled(mastra, 'favorites');\n      const honoredStarredOnly = favoritesEnabled && favoritedOnly === true;","sourceCodeStart":242,"sourceCodeEnd":278,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-agents.ts#L242-L278","documentation":"After storage is configured, the handler calls storage.getStore('agents') to get the agents domain store; a storage adapter that doesn't implement/support the 'agents' domain returns undefined, producing HTTP 500. This distinguishes 'storage missing entirely' from 'storage present but the agents domain is unavailable'.","triggerScenarios":"GET /stored/agents against a custom or partial storage adapter that doesn't provide the agents store; storage adapter connected but domain stores not initialized; using a legacy adapter version lacking the agents domain.","commonSituations":"Custom MastraStorage implementation that returns null from getStore for 'agents'; version mismatch where @mastra/core storage interface changed and a third-party adapter no longer registers the agents domain; adapter initialized lazily and initialization failed silently.","solutions":["Use an official storage adapter (@mastra/pg, @mastra/libsql, @mastra/upstash) that supports the agents domain","Update the storage adapter package to a version compatible with your @mastra/core version","Check adapter logs for failed initialization of domain stores","If using a custom adapter, implement getStore('agents') returning a functional agents store"],"exampleFix":"// before\nstorage: new MyMinimalStore() // getStore('agents') -> undefined\n// after\nstorage: new PostgresStore({ connectionString: process.env.DATABASE_URL })","handlingStrategy":"fallback","validationCode":"const store = await mastra.getStorage()?.getStore('agents');\nif (!store) throw new Error('Storage adapter lacks agents domain; use an official adapter');","typeGuard":"function hasAgentsStore(s: { getStore(d: string): Promise<unknown> }): Promise<boolean> {\n  return s.getStore('agents').then(Boolean);\n}","tryCatchPattern":"try {\n  return await get('/stored/agents');\n} catch (e) {\n  if ((e as any).status === 500 && /Agents storage domain/.test((e as any).message)) {\n    throw new Error('Replace/upgrade the storage adapter to one supporting the agents domain');\n  }\n  throw e;\n}","preventionTips":["Use official adapters (@mastra/pg, @mastra/libsql) for the agents domain","Keep adapter and @mastra/core versions in lockstep","Smoke-test getStore('agents') after any storage change","Pin and test storage adapter versions in CI"],"tags":["http-500","storage","stored-agents"],"backgroundTag":"storage-domain-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}