mastra-ai/mastra · error · HTTPException

Scorer '${scorerName}' not found

Error message

Scorer '${scorerName}' not found

What it means

The score-traces handler resolves the scorer with `mastra.getScorerById(scorerName)` and throws a 404 HTTPException when no registered scorer matches. Scorers must be registered on the Mastra instance (and thus exposed via getScorerById) before they can be applied to traces.

Source

Thrown at packages/server/src/server/handlers/observability.ts:410

  method: 'POST',
  path: '/observability/traces/score',
  responseType: 'json',
  bodySchema: scoreTracesRequestSchema,
  responseSchema: scoreTracesResponseSchema,
  summary: 'Score traces',
  description: 'Scores one or more traces using a specified scorer (fire-and-forget)',
  tags: ['Observability'],
  requiresAuth: true,
  handler: async ({ mastra, ...params }) => {
    try {
      // Validate storage exists before starting background task
      getStorage(mastra);

      const { scorerName, targets } = params;

      const scorer = mastra.getScorerById(scorerName);
      if (!scorer) {
        throw new HTTPException(404, { message: `Scorer '${scorerName}' not found` });
      }

      scoreTraces({
        scorerId: scorer.config.id || scorer.config.name,
        targets,
        mastra,
      }).catch(error => {
        const logger = mastra.getLogger();
        logger?.error(`Background trace scoring failed: ${error.message}`, error);
      });

      return {
        status: 'success',
        message: `Scoring started for ${targets.length} ${targets.length === 1 ? 'trace' : 'traces'}`,
        traceCount: targets.length,
      };
    } catch (error) {
      return handleError(error, 'Error processing trace scoring');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Register the scorer on the Mastra instance: `new Mastra({ scorers: { myScorer } })` (or the equivalent scorers config).
2. Use the scorer's registered ID (scorer.config.id || scorer.config.name) in the API call, not an arbitrary label.
3. List available scorers (GET scorers endpoint) and match the exact name/ID.
4. Restart/redeploy the server so newly added scorers are registered.

Example fix

// before
await scoreTracesApi({ scorerName: 'helpfulness' }); // not registered
// after
import { helpfulnessScorer } from './scorers';
new Mastra({ scorers: { helpfulness: helpfulnessScorer } });
await scoreTracesApi({ scorerName: 'helpfulness' });

const scorers = await fetch('/api/scorers').then(r => r.json());
if (!scorers.some(s => s.id === scorerName || s.name === scorerName)) {
  throw new Error(`Scorer '${scorerName}' is not registered`);
}

function isRegisteredScorer(name: string, scorers: { id?: string; name: string }[]): boolean {
  return scorers.some(s => s.id === name || s.name === name);
}

try {
  await scoreTraces({ scorerName });
} catch (e) {
  if (e.status === 404) {
    console.error(`Scorer '${scorerName}' not registered on server; register it in Mastra config`);
    return;
  }
  throw e;
}

When it happens

Trigger: Calling the score-traces API with a scorerName/ID that isn't registered on the Mastra instance — scorer never added to `new Mastra({ scorers: ... })`, wrong name/ID format (expects 'id' or namespaced ID), or scorer defined only in a different deployment.

Common situations: Renaming a scorer and forgetting to update callers; registering the scorer in a local dev config but not in the deployed server; confusing the scorer's display name with its registered ID; version upgrades that changed scorer registration APIs.

Related errors

• OBSERVABILITY_INVALID_CONFIG
• OBSERVABILITY_INVALID_INSTANCE_CONFIG
• Unable to locate pricing data JSONL at any known path: ${can
• defaultProjectName is required when mode is "create"
• MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE

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