mastra-ai/mastra · error · MastraError

MASTRA_GET_PROMPT_BLOCK_NOT_FOUND

MASTRA_GET_PROMPT_BLOCK_NOT_FOUND

Error message

Prompt block with key ${key} not found

What it means

Mastra.getPromptBlock(key) looks up a registered prompt block by its key in the internal #promptBlocks map. If no block was registered under that exact key, Mastra throws this MastraError (ErrorCategory.USER) because the caller referenced a block that does not exist. It is a lookup failure on user-supplied input, not an internal fault.

Source

Thrown at packages/core/src/mastra/index.ts:4126

   * @param key - Optional registration key (defaults to promptBlock.id)
   */
  public addPromptBlock(promptBlock: StorageResolvedPromptBlockType, key?: string): void {
    const blockKey = key || promptBlock.id;
    if (this.#promptBlocks[blockKey]) {
      return;
    }
    this.#promptBlocks[blockKey] = promptBlock;
  }

  /**
   * Retrieves a registered prompt block by its key.
   *
   * @throws {MastraError} When the prompt block with the specified key is not found
   */
  public getPromptBlock(key: string): StorageResolvedPromptBlockType {
    const block = this.#promptBlocks[key];
    if (!block) {
      throw new MastraError({
        id: 'MASTRA_GET_PROMPT_BLOCK_NOT_FOUND',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.USER,
        text: `Prompt block with key ${key} not found`,
      });
    }
    return block;
  }

  /**
   * Retrieves a registered prompt block by its ID.
   *
   * @throws {MastraError} When no prompt block is found with the specified ID
   */
  public getPromptBlockById(id: string): StorageResolvedPromptBlockType {
    for (const [, block] of Object.entries(this.#promptBlocks)) {
      if (block.id === id) {
        return block;

View on GitHub (pinned to 75dd419e61)

Solutions

1. List the registered prompt blocks (e.g. via the corresponding list/get-all accessor) and confirm the exact key, then use that key verbatim.
2. Fix typos or casing so the key matches the registration exactly (keys are matched with strict equality).
3. Register the missing block via registerPromptBlock (or the Mastra constructor config) before calling getPromptBlock.
4. If the key is user/config supplied, validate it against the known keys before lookup.

Example fix

// before
const block = mastra.getPromptBlock('system-instructions');
// after (check the actual registered key)
const blocks = mastra.getPromptBlocks();
console.log(Object.keys(blocks)); // e.g. ['systemInstructions']
const block = mastra.getPromptBlock('systemInstructions');

const blocks = mastra.getPromptBlocks?.() ?? {};
if (!(key in blocks)) {
  throw new Error(`Prompt block key "${key}" is not registered. Available: ${Object.keys(blocks).join(', ')}`);
}
const block = mastra.getPromptBlock(key);

try {
  const block = mastra.getPromptBlock(key);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_GET_PROMPT_BLOCK_NOT_FOUND') {
    // fall back to a default block or skip the block injection
  } else throw e;
}

When it happens

Trigger: Calling mastra.getPromptBlock('myKey') where 'myKey' was never passed when registering prompt blocks (or was registered under a different key, or with different casing/whitespace).

Common situations: Typo in the key string; key renamed during a refactor; reading the key from config/env where it is empty or stale; registering blocks conditionally so the block is absent in some environments.

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

• MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND
• Skill not found: ${invocation.skillName}.
• Environment not found: ${envArg}
• AGENT_SEND_TOOL_APPROVAL_AMBIGUOUS_SUSPENDED_RUNS
• AGENT_SEND_TOOL_APPROVAL_NO_ACTIVE_THREAD_RUN

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