{"record":{"id":"654ce0e77bbd5ab7","repo":"mastra-ai/mastra","slug":"mcp-clients-storage-domain-is-not-available-654ce0","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":"critical","filePath":"packages/server/src/server/handlers/stored-mcp-clients.ts","lineNumber":48,"sourceCode":"  path: '/stored/mcp-clients',\n  responseType: 'json',\n  queryParamSchema: listStoredMCPClientsQuerySchema,\n  responseSchema: listStoredMCPClientsResponseSchema,\n  summary: 'List stored MCP clients',\n  description: 'Returns a paginated list of all MCP client configurations stored in the database',\n  tags: ['Stored MCP Clients'],\n  requiresAuth: true,\n  handler: async ({ mastra, page, perPage, orderBy, status, authorId, metadata, 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 scope = await getStoredResourceScope(mastra, requestContext);\n      const result = await mcpClientStore.listResolved({\n        page,\n        perPage,\n        orderBy,\n        status,\n        authorId,\n        metadata: scopeStoredResourceMetadata(metadata, scope),\n      });\n\n      return result;\n    } catch (error) {\n      return handleError(error, 'Error listing stored MCP clients');\n    }\n  },\n});","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-mcp-clients.ts#L30-L66","documentation":"Storage is present but storage.getStore('mcpClients') returned nothing, so the list handler throws a 500 HTTPException. The mcpClients domain store backs resolved MCP client records. This signals the adapter does not support that domain or failed to initialize it.","triggerScenarios":"GET /api/mcp/clients/stored where the configured storage adapter lacks the 'mcpClients' store domain or its registration failed.","commonSituations":"Older storage adapter versions predating the mcpClients domain; core/storage version mismatch; failed schema migrations on startup; custom adapters implementing only core domains.","solutions":["Upgrade the storage adapter so it implements the mcpClients domain (match versions with @mastra/core).","Verify migrations/schema creation ran for the MCP clients tables.","Inspect startup logs for getStore/domain registration errors.","Switch to a first-party adapter known to support all current domains."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"const mcpStore = await storage.getStore('mcpClients');\nif (!mcpStore) throw new Error('mcpClients storage domain unavailable — upgrade/verify your storage adapter.');","typeGuard":null,"tryCatchPattern":"try {\n  const clients = await client.listStoredMCPClients({});\n} catch (e) {\n  if (isMastraServerError(e) && e.status === 500 && e.message.includes('storage domain')) {\n    // flag adapter/domain incompatibility\n  } else throw e;\n}","preventionTips":["Use a storage adapter version that implements the mcpClients domain.","Run migrations after upgrading so new domain tables are created.","Add an integration test asserting getStore('mcpClients') resolves."],"tags":["storage","store-domain","mcp","server"],"backgroundTag":"storage-domain-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}