What causes "Prompt block with id ${promptBlockId} not found" in mastra-ai/mastra?

Verify the promptBlockId exists (e.g. list prompt blocks first and use an id from the response).

mastra-ai/mastra · error · HTTPException

Prompt block with id ${promptBlockId} not found

Error message

Prompt block with id ${promptBlockId} not found

What it means

The promptBlocks store was reachable, but getById(promptBlockId) found no record, so the handler returns HTTP 404 naming the missing id. This is a lookup miss, not a configuration problem.

Source

Thrown at packages/server/src/server/handlers/prompt-block-versions.ts:60

  summary: 'List prompt block versions',
  description: 'Returns a paginated list of all versions for a stored prompt block',
  tags: ['Prompt Block Versions'],
  handler: async ({ mastra, promptBlockId, page, perPage, orderBy, 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' });
      }

      const promptBlock = await promptBlockStore.getById(promptBlockId);
      if (!promptBlock) {
        throw new HTTPException(404, { message: `Prompt block with id ${promptBlockId} not found` });
      }
      assertStoredResourceScope(promptBlock, await getStoredResourceScope(mastra, requestContext));

      const result = await promptBlockStore.listVersions({
        blockId: promptBlockId,
        page,
        perPage,
        orderBy,
      });

      return result;
    } catch (error) {
      return handleError(error, 'Error listing prompt block versions');
    }
  },
});

/**

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the promptBlockId exists (e.g. list prompt blocks first and use an id from the response).
Check you are connected to the storage instance/database that actually contains the block.
Recreate the prompt block if it was deleted; handle 404 in the client UI gracefully.

Example fix

// before
const versions = await fetch(`/api/prompt-blocks/${id}/versions`);
// after
const list = await fetch('/api/prompt-blocks').then(r => r.json());
if (!list.blocks.some(b => b.id === id)) throw new Error(`Unknown prompt block ${id}`);
const versions = await fetch(`/api/prompt-blocks/${id}/versions`);

Defensive patterns

Strategy: try-catch

Validate before calling

const blocks = await client.listPromptBlocks();
if (!blocks.blocks.some(b => b.id === promptBlockId)) {
  throw new Error(`Prompt block ${promptBlockId} does not exist in this storage`);
}

Try / catch

try {
  const versions = await client.getPromptBlockVersions(id);
} catch (e) {
  if (e.status === 404 && e.message.includes('not found')) {
    console.warn(`Prompt block ${id} missing; showing empty state`);
    return [];
  }
  throw e;
}

Prevention

Refresh cached prompt-block ids after database resets or environment switches.
Confirm the storage URL points at the environment that owns the block.
Handle 404 in UI flows instead of assuming ids are always valid.

When it happens

Trigger: GET/POST a prompt-block-versions route with a promptBlockId that has no row in the promptBlocks store (deleted block, wrong id, or id from another environment/database).

Common situations: Stale ids cached in the playground after a database reset; pointing staging UI at a prod database or vice versa; typos or trimmed/uuid-mismatched ids in scripts.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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