mastra-ai/mastra · error · MastraError

MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND

MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND

Error message

Prompt block with id ${id} not found

What it means

getPromptBlockById(id) iterates all registered prompt blocks and returns the first whose id matches. When no block has that id, Mastra throws this MastraError. Note this searches by the block's own id property, which is distinct from the registration key used by getPromptBlock.

Source

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

        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;
      }
    }

    throw new MastraError({
      id: 'MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND',
      domain: ErrorDomain.MASTRA,
      category: ErrorCategory.USER,
      text: `Prompt block with id ${id} not found`,
    });
  }

  /**
   * Removes a prompt block from the Mastra instance by its key or ID.
   *
   * @param keyOrId - The prompt block key or ID to remove
   * @returns true if a prompt block was removed, false if not found
   */
  public removePromptBlock(keyOrId: string): boolean {
    if (this.#promptBlocks[keyOrId]) {
      delete this.#promptBlocks[keyOrId];
      return true;
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Enumerate the registered prompt blocks and verify each block's id, then pass the exact id.
2. If you actually know the registration key, use getPromptBlock(key) instead of the id-based lookup.
3. Register the block with the expected id, or update the caller/config to use the id that was actually assigned.
4. Validate that the id exists in the collection before calling the getter.

Example fix

// before
const block = mastra.getPromptBlockById('block-1'); // never registered with this id
// after
const block = mastra.getPromptBlockById('kb-summary-v2'); // matches block.id === 'kb-summary-v2'

const blocks = mastra.getPromptBlocks?.() ?? {};
const exists = Object.values(blocks).some(b => b.id === id);
if (!exists) throw new Error(`No prompt block with id "${id}" registered`);

try {
  const block = mastra.getPromptBlockById(id);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND') {
    return null; // treat as absent, don't crash the caller
  } throw e;
}

When it happens

Trigger: Calling mastra.getPromptBlockById('abc-123') where no registered prompt block's block.id equals 'abc-123'; passing a key where an id is expected (or vice versa); the block was never registered.

Common situations: Confusing the registration key with the block id; stale id after blocks were regenerated; integration/agent config referencing a block from another Mastra instance.

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_NOT_FOUND
• Skill not found: ${invocation.skillName}.
• Plugin id mismatch: registry has "${record.id}" but module e
• MASTRA_GET_TOOL_BY_ID_NOT_FOUND
• MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND

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