{"record":{"id":"12340ab99307fa67","repo":"mastra-ai/mastra","slug":"could-not-derive-agent-id-from-name-please-provid","errorCode":null,"errorMessage":"Could not derive agent ID from name. Please provide an explicit id.","messagePattern":"Could not derive agent ID from name\\. Please provide an explicit id\\.","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/stored-agents.ts","lineNumber":598,"sourceCode":"    requestContextSchema,\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      // 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 agent ID from name. Please provide an explicit id.',\n        });\n      }\n\n      // Check if agent with this ID already exists\n      const existing = await agentsStore.getById(id);\n      if (existing) {\n        throw new HTTPException(409, { message: `Agent with id ${id} already exists` });\n      }\n\n      // Force authorId from the authenticated caller; ignore any body-provided value.\n      // No owner = always public (no auth / no user context).\n      // With an owner, respect the client's choice, defaulting to 'private'.\n      const authorId = getCallerAuthorId(requestContext) ?? undefined;\n      const visibility = authorId ? (bodyVisibility ?? 'private') : 'public';\n\n      // Reject oversized avatar images before writing to storage.\n      validateMetadataAvatarUrl(metadata);","sourceCodeStart":580,"sourceCodeEnd":616,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/stored-agents.ts#L580-L616","documentation":"Thrown with HTTP 400 when creating a stored agent without an explicit `id` and the server cannot derive one: `providedId || toSlug(name)` produced an empty string. The ID is required as the primary key for the stored agent record, so the request is rejected as a client (bad request) error.","triggerScenarios":"POST create-agent request where neither `id` nor a non-empty `name` is supplied, or where `name` contains only characters that toSlug strips (e.g. name === '---' or '   '), yielding an empty slug.","commonSituations":"A form/UI submitting an agent with a blank name; programmatic clients omitting both id and name; a name made entirely of special characters that slugify to nothing; translation/localization replacing the name with punctuation-only text.","solutions":["Pass an explicit `id` in the request body when the name may be empty or non-slugifiable","Ensure `name` is a non-empty string containing at least one alphanumeric character so toSlug yields a usable ID","Validate on the client before calling the API: require name or id non-empty","Trim/sanitize the name and retry with a meaningful identifier"],"exampleFix":"// before\nawait createAgent({ name: '---' });\n\n// after\nawait createAgent({ id: 'my-custom-agent', name: '---' });","handlingStrategy":"validation","validationCode":"if (!id && !(name && /\\w/.test(name))) {\n  throw new Error('Provide an explicit id, or a name containing at least one alphanumeric character.');\n}","typeGuard":"function canDeriveId(input: { id?: string; name?: string }): input is { id: string } | { name: string } {\n  return Boolean(input.id || (input.name && toSlug(input.name)));\n}","tryCatchPattern":"try {\n  await createStoredAgent({ name });\n} catch (e) {\n  if (isHttpError(e) && e.status === 400 && /derive agent ID/.test(e.message)) {\n    return createStoredAgent({ id: promptForId(), name });\n  }\n  throw e;\n}","preventionTips":["Require `id` in programmatic clients instead of relying on slug derivation","Validate name non-empty and alphanumeric-bearing in forms before submit","Render a preview of the derived slug in the UI so users see the resulting ID"],"tags":["validation","bad-request","slug","agent-id"],"backgroundTag":"missing-required-identifier","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}