mastra-ai/mastra · error · MastraError

MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND

MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND

Error message

Processor with id ${id} not found

What it means

getProcessorById reads the internal processor registry (#processors) and throws this MastraError when it is empty/undefined. Unlike the by-id prompt-block error, this one fires only when no processors are registered at all — a lookup against a missing collection.

Source

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

   *
   * @example
   * ```typescript
   * const mastra = new Mastra({
   *   processors: {
   *     validator: validatorProcessor
   *   }
   * });
   *
   * const processor = mastra.getProcessorById('validator-processor-id');
   * ```
   */
  public getProcessorById<TProcessorName extends keyof TProcessors>(
    id: TProcessors[TProcessorName]['id'],
  ): TProcessors[TProcessorName] {
    const allProcessors = this.#processors;

    if (!allProcessors) {
      throw new MastraError({
        id: 'MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND',
        domain: ErrorDomain.MASTRA,
        category: ErrorCategory.USER,
        text: `Processor with id ${id} not found`,
      });
    }

    // First try to find by internal ID
    for (const processor of Object.values(allProcessors)) {
      if (processor.id === id) {
        return processor as TProcessors[TProcessorName];
      }
    }

    // Fallback to searching by registration key
    const processorByKey = allProcessors[id];
    if (processorByKey) {
      return processorByKey as TProcessors[TProcessorName];

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register processors (constructor config or the register API) before querying by id.
2. Check the processors listing accessor for emptiness before calling getProcessorById.
3. Ensure the code path constructing Mastra in the current environment actually registers processors.
4. Catch this error where an empty processor set is acceptable and treat it as 'no processor'.

Example fix

// before
const mastra = new Mastra({ agents });
const p = mastra.getProcessorById('pii-redactor'); // throws: no processors registered
// after
const mastra = new Mastra({ agents, processors: { piiRedactor } });
const p = mastra.getProcessorById('piiRedactor');

const procs = mastra.getProcessors?.();
if (!procs || Object.keys(procs).length === 0) {
  throw new Error('No processors registered on this Mastra instance');
}

try {
  const processor = mastra.getProcessorById(id);
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_GET_PROCESSOR_BY_ID_NOT_FOUND') {
    // empty registry: continue without the processor
  } else throw e;
}

When it happens

Trigger: Calling mastra.getProcessorById(id) on a Mastra instance constructed without processors and without any later processor registration.

Common situations: Runtime/tooling code assuming processors were configured on the instance; building a Mastra instance for inference only (no processors) while a helper still queries them; config gating that skips processor registration 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_TOOL_BY_ID_NOT_FOUND
• Aborted by processor
• Skill not found: ${invocation.skillName}.
• MASTRA_GET_PROMPT_BLOCK_NOT_FOUND
• MASTRA_GET_PROMPT_BLOCK_BY_ID_NOT_FOUND

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