{"record":{"id":"3c1389f42c8589bb","repo":"mastra-ai/mastra","slug":"scorer-scorername-not-found","errorCode":null,"errorMessage":"Scorer '${scorerName}' not found","messagePattern":"Scorer '(.+?)' not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/observability.ts","lineNumber":410,"sourceCode":"  method: 'POST',\n  path: '/observability/traces/score',\n  responseType: 'json',\n  bodySchema: scoreTracesRequestSchema,\n  responseSchema: scoreTracesResponseSchema,\n  summary: 'Score traces',\n  description: 'Scores one or more traces using a specified scorer (fire-and-forget)',\n  tags: ['Observability'],\n  requiresAuth: true,\n  handler: async ({ mastra, ...params }) => {\n    try {\n      // Validate storage exists before starting background task\n      getStorage(mastra);\n\n      const { scorerName, targets } = params;\n\n      const scorer = mastra.getScorerById(scorerName);\n      if (!scorer) {\n        throw new HTTPException(404, { message: `Scorer '${scorerName}' not found` });\n      }\n\n      scoreTraces({\n        scorerId: scorer.config.id || scorer.config.name,\n        targets,\n        mastra,\n      }).catch(error => {\n        const logger = mastra.getLogger();\n        logger?.error(`Background trace scoring failed: ${error.message}`, error);\n      });\n\n      return {\n        status: 'success',\n        message: `Scoring started for ${targets.length} ${targets.length === 1 ? 'trace' : 'traces'}`,\n        traceCount: targets.length,\n      };\n    } catch (error) {\n      return handleError(error, 'Error processing trace scoring');","sourceCodeStart":392,"sourceCodeEnd":428,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/observability.ts#L392-L428","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the scorer on the Mastra instance: `new Mastra({ scorers: { myScorer } })` (or the equivalent scorers config).","Use the scorer's registered ID (scorer.config.id || scorer.config.name) in the API call, not an arbitrary label.","List available scorers (GET scorers endpoint) and match the exact name/ID.","Restart/redeploy the server so newly added scorers are registered."],"exampleFix":"// before\nawait scoreTracesApi({ scorerName: 'helpfulness' }); // not registered\n// after\nimport { helpfulnessScorer } from './scorers';\nnew Mastra({ scorers: { helpfulness: helpfulnessScorer } });\nawait scoreTracesApi({ scorerName: 'helpfulness' });","handlingStrategy":"validation","validationCode":"const scorers = await fetch('/api/scorers').then(r => r.json());\nif (!scorers.some(s => s.id === scorerName || s.name === scorerName)) {\n  throw new Error(`Scorer '${scorerName}' is not registered`);\n}","typeGuard":"function isRegisteredScorer(name: string, scorers: { id?: string; name: string }[]): boolean {\n  return scorers.some(s => s.id === name || s.name === name);\n}","tryCatchPattern":"try {\n  await scoreTraces({ scorerName });\n} catch (e) {\n  if (e.status === 404) {\n    console.error(`Scorer '${scorerName}' not registered on server; register it in Mastra config`);\n    return;\n  }\n  throw e;\n}","preventionTips":["Register every scorer in `new Mastra({ scorers: ... })` and deploy before scoring.","Score with the registered ID, not a display label.","Keep scorer names in a shared constant imported by both config and callers.","Add a startup check that all expected scorers resolve via getScorerById."],"tags":["http-404","scorers","configuration","observability"],"backgroundTag":"scorer-not-registered","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}