mastra-ai/mastra · error · HTTPException

Could not derive agent ID from name. Please provide an expli

Error message

Could not derive agent ID from name. Please provide an explicit id.

What it means

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.

Source

Thrown at packages/server/src/server/handlers/stored-agents.ts:598

    requestContextSchema,
  }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const agentsStore = await storage.getStore('agents');
      if (!agentsStore) {
        throw new HTTPException(500, { message: 'Agents storage domain is not available' });
      }

      // Derive ID from name if not explicitly provided
      const id = providedId || toSlug(name);

      if (!id) {
        throw new HTTPException(400, {
          message: 'Could not derive agent ID from name. Please provide an explicit id.',
        });
      }

      // Check if agent with this ID already exists
      const existing = await agentsStore.getById(id);
      if (existing) {
        throw new HTTPException(409, { message: `Agent with id ${id} already exists` });
      }

      // Force authorId from the authenticated caller; ignore any body-provided value.
      // No owner = always public (no auth / no user context).
      // With an owner, respect the client's choice, defaulting to 'private'.
      const authorId = getCallerAuthorId(requestContext) ?? undefined;
      const visibility = authorId ? (bodyVisibility ?? 'private') : 'public';

      // Reject oversized avatar images before writing to storage.
      validateMetadataAvatarUrl(metadata);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an explicit `id` in the request body when the name may be empty or non-slugifiable
2. Ensure `name` is a non-empty string containing at least one alphanumeric character so toSlug yields a usable ID
3. Validate on the client before calling the API: require name or id non-empty
4. Trim/sanitize the name and retry with a meaningful identifier

Example fix

// before
await createAgent({ name: '---' });

// after
await createAgent({ id: 'my-custom-agent', name: '---' });

if (!id && !(name && /\w/.test(name))) {
  throw new Error('Provide an explicit id, or a name containing at least one alphanumeric character.');
}

function canDeriveId(input: { id?: string; name?: string }): input is { id: string } | { name: string } {
  return Boolean(input.id || (input.name && toSlug(input.name)));
}

try {
  await createStoredAgent({ name });
} catch (e) {
  if (isHttpError(e) && e.status === 400 && /derive agent ID/.test(e.message)) {
    return createStoredAgent({ id: promptForId(), name });
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• bad request: ${responseText}
• GitHub repository is invalid.
• GitHub capabilities require an owner/repository source.
• JSON.stringify(errorResponse)
• Processor ID is required

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/12340ab99307fa67. Report an issue: GitHub.