{"record":{"id":"63596c6e87a5176d","repo":"mastra-ai/mastra","slug":"no-root-agent-run-span-found-in-trace","errorCode":null,"errorMessage":"No root agent_run span found in trace","messagePattern":"No root agent_run span found in trace","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/evals/scoreTraces/utils.ts","lineNumber":261,"sourceCode":"    // There should only be one model generation span per agent run which is a direct child of the root agent span\n    return directLLMSpans[0]!;\n  }\n\n  throw new Error('No model generation span found in trace');\n}\n\n/**\n * Extract common trace validation and span tree building logic\n */\nfunction prepareTraceForTransformation(trace: TraceRecord) {\n  validateTrace(trace);\n  const spanTree = buildSpanTree(trace.spans);\n\n  // Find the root agent run span\n  const rootAgentSpan = spanTree.rootSpans.find(span => span.spanType === 'agent_run') as SpanRecord | undefined;\n\n  if (!rootAgentSpan) {\n    throw new Error('No root agent_run span found in trace');\n  }\n\n  return { spanTree, rootAgentSpan };\n}\n\nexport function transformTraceToScorerInputAndOutput(trace: TraceRecord): {\n  input: ScorerRunInputForAgent;\n  output: ScorerRunOutputForAgent;\n} {\n  const { spanTree, rootAgentSpan } = prepareTraceForTransformation(trace);\n\n  if (!rootAgentSpan.output) {\n    throw new Error('Root agent span has no output');\n  }\n\n  // Build input\n  const primaryLLMSpan = findPrimaryLLMSpan(spanTree, rootAgentSpan);\n  const inputMessages = extractInputMessages(rootAgentSpan);","sourceCodeStart":243,"sourceCodeEnd":279,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/evals/scoreTraces/utils.ts#L243-L279","documentation":"prepareTraceForTransformation throws this when no span in the trace's root spans has spanType 'agent_run'. The scoring transformation is designed around a root agent run span and cannot proceed without one.","triggerScenarios":"Scoring a trace that was not produced by an agent run — e.g. a workflow-only trace, a trace whose agent_run span is nested (not at root) due to instrumentation changes, or a manually selected wrong traceId.","commonSituations":"Pointing the score-traces workflow at workflow traces; version drift where span types/hierarchy changed between @mastra/core releases; multiple root spans with the agent run not among them.","solutions":["Score only traces originating from agent runs (verify root span type before scoring)","Align @mastra/core and any instrumentation/tracing package versions so span hierarchy matches","Check the traceId — fetch and inspect the trace to confirm it is the intended agent run"],"exampleFix":"// before\nscoreTrace({ trace: workflowTrace });\n// after\nif (!getTraceRoots(workflowTrace).some(s => s.spanType === 'agent_run')) skipScoring(workflowTrace.traceId);\nelse scoreTrace({ trace: workflowTrace });","handlingStrategy":"type-guard","validationCode":"const roots = buildSpanTree(trace.spans).rootSpans;\nif (!roots.some(s => s.spanType === 'agent_run')) throw new Error('Trace is not an agent run');","typeGuard":"function isAgentRunTrace(t: TraceRecord): boolean {\n  return buildSpanTree(t.spans).rootSpans.some(s => s.spanType === 'agent_run');\n}","tryCatchPattern":"try {\n  prepareTraceForTransformation(trace);\n} catch (e) {\n  if (e instanceof Error && e.message === 'No root agent_run span found in trace') {\n    logger.warn('Skipping scoring: not an agent-run trace', { traceId: trace.traceId });\n  } else throw e;\n}","preventionTips":["Route only agent-run traces into the score-traces workflow","Confirm the correct traceId is selected (not a workflow trace)","Check for span-hierarchy changes after upgrading @mastra/core","Log root span types when scoring fails to ease diagnosis"],"tags":["trace","agent-run","span-type"],"backgroundTag":"missing-agent-run-root-span","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}