mastra-ai/mastra · error · MastraError

MASTRA_SCORER_NOT_FOUND

MASTRA_SCORER_NOT_FOUND

Error message

Scorer with ID ${scorerId} not found

What it means

The onScorer hook resolves the scorer by id through findScorer(mastra, entityId, entityType, scorerId); if no scorer with that ID is registered (locally or via storage), it throws this USER-category MastraError. It means the scoring hook was invoked for a scorer that the Mastra instance does not know about.

Source

Thrown at packages/core/src/mastra/hooks.ts:48

      mastra.getLogger()?.warn('Storage not found, skipping score validation and saving');
      return;
    }

    const entityId = hookData.entity.id as string;
    const entityType = hookData.entityType;
    const scorer = hookData.scorer;
    const scorerId = scorer.id as string;

    if (!scorerId) {
      mastra.getLogger()?.warn('Scorer ID not found, skipping score validation and saving');
      return;
    }

    try {
      const scorerToUse = await findScorer(mastra, entityId, entityType, scorerId);

      if (!scorerToUse) {
        throw new MastraError({
          id: 'MASTRA_SCORER_NOT_FOUND',
          domain: ErrorDomain.MASTRA,
          category: ErrorCategory.USER,
          text: `Scorer with ID ${scorerId} not found`,
        });
      }

      let input = hookData.input;
      let output = hookData.output;

      const { structuredOutput, ...rest } = hookData;

      const currentSpan = hookData.tracingContext?.currentSpan;
      const traceId = currentSpan?.isValid ? currentSpan.traceId : undefined;
      const spanId = currentSpan?.isValid ? currentSpan.id : undefined;
      const targetCorrelationContext = currentSpan?.isValid ? currentSpan.getCorrelationContext?.() : undefined;
      const targetMetadata = currentSpan?.isValid && currentSpan.metadata ? { ...currentSpan.metadata } : undefined;
      const runResult = await scorerToUse.scorer.run({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the scorer before the run: mastra.registerScorer({ scorer, name: '...' }) and use the registered id.
2. Verify the exact id string matches the registered scorer name/id (watch casing/typos).
3. Ensure the same Mastra instance that runs the agent is the one with the scorer registered.
4. Check entity type (agent/workflow) registration path — findScorer looks up per entityId/entityType, so confirm the scorer is attached to the right entity.
5. Import the scorer registration in the entrypoint so it actually executes before the hook runs.

Example fix

// before
const result = await agent.generate('hi', { scorers: [{ scorerId: 'answer-relevance' }] }); // never registered
// after
mastra.registerScorer({ scorer: new AnswerRelevanceScorer(), name: 'answer-relevance' });
const result = await agent.generate('hi', { scorers: [{ scorerId: 'answer-relevance' }] });

const registered = mastra.getScorers?.() ?? [];
if (!registered.some(s => (s.name ?? s.id) === scorerId)) {
  throw new Error(`Scorer ${scorerId} must be registered via mastra.registerScorer() before use`);
}

try {
  await runWithScorers();
} catch (e) {
  if (e instanceof MastraError && e.id === 'MASTRA_SCORER_NOT_FOUND') {
    console.error(`Scorer ${scorerId} not registered on this Mastra instance`);
  }
  throw e;
}

When it happens

Trigger: Calling mastra.getScorer()/the onScorer hook with a scorerId string that was never registered with mastra.registerScorer(), a typo'd id, or a scorer registered on a different Mastra instance than the one executing the agent run.

Common situations: Copy-pasting a scorer id from docs/examples without registering it; registering scorers after the agent run already started; renaming a scorer and not updating references; running scorers in a service with its own Mastra instance that lacks the registration.

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

• TokenCostControl requires observability storage with getMetr
• Scorer '${scorerName}' not found
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Auth0 domain and audience are required, please provide them

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