{"record":{"id":"bc3fae50edc57e6a","repo":"mastra-ai/mastra","slug":"could-not-derive-mcp-client-id-from-name-please-p","errorCode":null,"errorMessage":"Could not derive MCP client ID from name. Please provide an explicit id.","messagePattern":"Could not derive MCP client ID from name\\. Please provide an explicit id\\.","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/stored-mcp-clients.ts","lineNumber":140,"sourceCode":"  requiresAuth: true,\n  handler: async ({ mastra, id: providedId, authorId, metadata, name, description, servers, 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      // Derive ID from name if not explicitly provided\n      const id = providedId || toSlug(name);\n\n      if (!id) {\n        throw new HTTPException(400, {\n          message: 'Could not derive MCP client ID from name. Please provide an explicit id.',\n        });\n      }\n\n      // Check if MCP client with this ID already exists\n      const existing = await mcpClientStore.getById(id);\n      if (existing) {\n        throw new HTTPException(409, { message: `MCP client with id ${id} already exists` });\n      }\n\n      await mcpClientStore.create({\n        mcpClient: {\n          id,\n          authorId,\n          metadata: scopeStoredResourceMetadata(metadata, await getStoredResourceScope(mastra, requestContext)),\n          name,\n          description,\n          servers,","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-mcp-clients.ts#L122-L158","documentation":"HTTP 400 thrown when neither an explicit id nor a name that survives slugification is provided, so the handler cannot derive a unique MCP client ID (id = providedId || toSlug(name)). It is a client-input validation failure, returned before any storage writes.","triggerScenarios":"POST create call where `id` is absent and `name` is empty, whitespace-only, or composed solely of characters that toSlug strips (e.g. '---', '///').","commonSituations":"Frontend form submitting an empty name; programmatic clients sending only metadata; localization edge cases where the name contains only non-ASCII/symbol characters stripped by the slugger.","solutions":["Pass an explicit `id` alongside (or instead of) `name` in the create payload.","Ensure `name` contains slug-derivable characters (letters/numbers).","Validate the payload client-side before POSTing.","Trim/normalize the name before sending."],"exampleFix":"// before\nawait fetch('/api/mcp/clients', { method: 'POST', body: JSON.stringify({ name: '///' }) });\n// after\nawait fetch('/api/mcp/clients', { method: 'POST', body: JSON.stringify({ name: 'My Client', id: 'my-client' }) });","handlingStrategy":"validation","validationCode":"function validateClientPayload(p: { id?: string; name?: string }) {\n  if (!p.id && !(p.name && p.name.trim().replace(/[^a-zA-Z0-9]/g, '').length > 0)) {\n    throw new Error('Provide an explicit id or a slug-derivable name');\n  }\n}","typeGuard":"function hasDerivableId(p: { id?: string; name?: string }): boolean {\n  return Boolean(p.id && p.id.trim()) || Boolean(p.name && /\\w/.test(p.name));\n}","tryCatchPattern":"try {\n  await createMcpClient(payload);\n} catch (e) {\n  if (String(e).includes('Could not derive MCP client ID')) {\n    await createMcpClient({ ...payload, id: crypto.randomUUID() });\n  } else throw e;\n}","preventionTips":["Always send an explicit id for programmatic creation.","Validate name non-empty on forms before submit.","Avoid names made only of punctuation/symbols.","Generate fallback ids server-side of your app logic (uuid/slug)."],"tags":["validation","mcp","http-400","input"],"backgroundTag":"invalid-request-payload","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}