{"record":{"id":"5dac9067fde8792a","repo":"mastra-ai/mastra","slug":"mcp-client-with-id-mcpclientid-not-found","errorCode":null,"errorMessage":"MCP client with id ${mcpClientId} not found","messagePattern":"MCP client with id (.+?) not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/mcp-client-versions.ts","lineNumber":59,"sourceCode":"  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');\n    }\n  },\n});\n\n/**","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/mcp-client-versions.ts#L41-L77","documentation":"The MCP client versions list handler looks up the MCP client by ID via mcpClientStore.getById(mcpClientId) and throws HTTPException 404 if no record exists. It signals the client asked for version history of an MCP client ID that is not in storage. The ID is interpolated into the message to make the missing resource unambiguous.","triggerScenarios":"GET the versions endpoint with an mcpClientId that was never registered, was deleted, or belongs to a different storage backend/environment than the one the server is using.","commonSituations":"Stale UI/URL pointing at a deleted MCP client; pointing the client at a server whose storage points at a different database than where the client was created; typo'd or truncated client ID; scope mismatch after multi-tenant scoping was added (assertStoredResourceScope may also reject).","solutions":["Verify mcpClientId against the list of registered MCP clients (list endpoint) and use a valid ID.","Confirm the server's storage points at the same database/environment where the MCP client was created.","If the client was deleted intentionally, remove stale references from the UI/bookmarks.","Check tenant/scope: the caller's scope must match the stored client's resource scope."],"exampleFix":"// before: hard-coded stale ID\nawait fetch('/api/mcp-clients/clx_old123/versions');\n// after: resolve a fresh ID from the list endpoint\nconst clients = await fetch('/api/mcp-clients').then(r => r.json());\nconst id = clients.find(c => c.name === 'my-mcp-client').id;\nawait fetch(`/api/mcp-clients/${id}/versions`);","handlingStrategy":"validation","validationCode":"const clients = await fetch('/api/mcp-clients').then(r => r.json());\nif (!clients.some(c => c.id === mcpClientId)) {\n  throw new Error(`MCP client ${mcpClientId} does not exist; pick a valid id`);\n}","typeGuard":"function isNotFoundError(e: unknown): e is Error & { status: 404 } {\n  return e instanceof Error && (e as any).status === 404;\n}","tryCatchPattern":"try {\n  return await fetch(`/api/mcp-clients/${mcpClientId}/versions`).then(r => {\n    if (r.status === 404) throw Object.assign(new Error('not found'), { status: 404 });\n    return r.json();\n  });\n} catch (e) {\n  if ((e as any).status === 404) {\n    return showClientMissingNotice(mcpClientId); // refresh list / clean stale UI\n  }\n  throw e;\n}","preventionTips":["Always resolve MCP client IDs from the list endpoint rather than persisting them long-term.","Revalidate stale IDs after deletes or environment/storage switches.","Ensure client scope/tenant matches the stored client's scope before calling."],"tags":["http-404","not-found","mcp"],"backgroundTag":"resource-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}