mastra-ai/mastra · error · HTTPException

Could not derive prompt block ID from name. Please provide a

Error message

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

What it means

When creating a stored prompt block without an explicit `id`, the server derives one by slugifying the provided `name` via `toSlug(name)`. If the result is an empty string (e.g. the name contained only characters stripped by slugification), creation is aborted with this 400 error asking for an explicit id. The slug must be non-empty to be a usable record key.

Source

Thrown at packages/server/src/server/handlers/stored-prompt-blocks.ts:179

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

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

      const promptBlockStore = await storage.getStore('promptBlocks');
      if (!promptBlockStore) {
        throw new HTTPException(500, { message: 'Prompt blocks 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 prompt block ID from name. Please provide an explicit id.',
        });
      }

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

      await promptBlockStore.create({
        promptBlock: {
          id,
          authorId,
          metadata: scopeStoredResourceMetadata(metadata, await getStoredResourceScope(mastra, requestContext)),
          name,
          description,
          content,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass an explicit `id` field in the create request body
2. Provide a `name` that slugifies to a non-empty value (include letters or numbers)
3. Sanitize names client-side before submitting and fall back to an explicit id

Example fix

// before
await client.createStoredPromptBlock({ name: '!!!' })
// after
await client.createStoredPromptBlock({ id: 'my-block-1', name: '!!!' })

function slugify(name: string): string {
  return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
}
if (!id && !slugify(name)) {
  throw new Error(`Name "${name}" slugifies to an empty id; provide an explicit id`);
}

function canDeriveId(body: { id?: string; name: string }): boolean {
  return Boolean(body.id || body.name.replace(/[^a-zA-Z0-9]/g, ''));
}

When it happens

Trigger: POST /stored/prompt-blocks with a body that omits `id` and has a `name` consisting solely of characters removed by toSlug (e.g. '!!!', ' ', '///', or an emoji-only name).

Common situations: Programmatic generation of prompt blocks where names are templated or user-supplied and may collapse to empty after slugification; names containing only non-ASCII/special characters.

Related errors

• GitHub repository is invalid.
• GitHub capabilities require an owner/repository source.
• MASTRA_SERVER_API_INVALID_ROUTE_OPTIONS
• JSON.stringify(errorResponse)
• server.drainTimeout must be a finite number between 0 and 21

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