{"record":{"id":"72e8f5ff76f3ed1a","repo":"mastra-ai/mastra","slug":"mcp-clients-storage-domain-is-not-available","errorCode":null,"errorMessage":"MCP clients storage domain is not available","messagePattern":"MCP clients storage domain is not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/mcp-client-versions.ts","lineNumber":54,"sourceCode":"  requiresAuth: true,\n  responseType: 'json',\n  pathParamSchema: mcpClientVersionPathParams,\n  queryParamSchema: listMCPClientVersionsQuerySchema,\n  responseSchema: listMCPClientVersionsResponseSchema,\n  summary: 'List MCP client versions',\n  description: 'Returns a paginated list of all versions for a stored MCP client',\n  tags: ['MCP Client Versions'],\n  handler: async ({ mastra, mcpClientId, 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 mcpClientStore = await storage.getStore('mcpClients');\n      if (!mcpClientStore) {\n        throw new HTTPException(500, { message: 'MCP clients storage domain is not available' });\n      }\n\n      const mcpClient = await mcpClientStore.getById(mcpClientId);\n      if (!mcpClient) {\n        throw new HTTPException(404, { message: `MCP client with id ${mcpClientId} not found` });\n      }\n      assertStoredResourceScope(mcpClient, await getStoredResourceScope(mastra, requestContext));\n\n      const result = await mcpClientStore.listVersions({\n        mcpClientId,\n        page,\n        perPage,\n        orderBy,\n      });\n\n      return result;\n    } catch (error) {\n      return handleError(error, 'Error listing MCP client versions');","sourceCodeStart":36,"sourceCodeEnd":72,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp-client-versions.ts#L36-L72","documentation":"After confirming storage exists, the MCP client versions handler resolves the 'mcpClients' storage domain via storage.getStore('mcpClients') and throws HTTPException 500 if that domain is not available. This means the configured storage adapter exists but does not implement (or failed to provide) the MCP clients domain, so version history cannot be read. It indicates an adapter capability/version gap rather than missing storage altogether.","triggerScenarios":"GET the MCP client versions endpoint against a storage adapter that lacks an mcpClients store (older or minimal adapter, or a domain the adapter didn't register).","commonSituations":"Using a custom or third-party storage adapter that hasn't implemented the mcpClients domain; an outdated storage package version predating the mcpClients domain; a storage backend that partially initialized.","solutions":["Upgrade @mastra storage packages so the configured adapter implements the mcpClients domain.","Switch to a storage adapter that supports the mcpClients domain (e.g. an official LibSQL/Postgres/Upstash adapter at a current version).","If using a custom adapter, implement the mcpClients store methods required by the server."],"exampleFix":"// before: old adapter without the domain\nstorage: new MyCustomStore({ url }),\n// after: current official adapter supporting mcpClients\nstorage: new LibSQLStore({ url: process.env.DATABASE_URL }),","handlingStrategy":"fallback","validationCode":"const storage = mastra.getStorage();\nconst store = storage ? await storage.getStore('mcpClients') : null;\nif (!store) {\n  console.warn('Storage adapter lacks mcpClients domain; upgrade or switch adapter');\n}","typeGuard":"function supportsMcpClients(storage: MastraStorage | null): boolean {\n  return !!storage && typeof (storage as any).getStore === 'function' && !!(storage as any).stores?.mcpClients;\n}","tryCatchPattern":"try {\n  return await getMcpClientVersions(id);\n} catch (e) {\n  if (e.status === 500 && /storage domain is not available/.test(e.message)) {\n    return { versions: [], unsupported: true }; // degrade gracefully\n  }\n  throw e;\n}","preventionTips":["Pin and regularly upgrade official storage adapters so new domains are implemented.","Write an integration test that calls getStore('mcpClients') against your configured adapter.","Avoid untested custom adapters for features requiring newer storage domains."],"tags":["storage","mcp","adapter","http-500"],"backgroundTag":"storage-domain-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}