mastra-ai/mastra · error · Error

No root agent_run span found in trace

Error message

No root agent_run span found in trace

What it means

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.

Source

Thrown at packages/core/src/evals/scoreTraces/utils.ts:261

    // There should only be one model generation span per agent run which is a direct child of the root agent span
    return directLLMSpans[0]!;
  }

  throw new Error('No model generation span found in trace');
}

/**
 * Extract common trace validation and span tree building logic
 */
function prepareTraceForTransformation(trace: TraceRecord) {
  validateTrace(trace);
  const spanTree = buildSpanTree(trace.spans);

  // Find the root agent run span
  const rootAgentSpan = spanTree.rootSpans.find(span => span.spanType === 'agent_run') as SpanRecord | undefined;

  if (!rootAgentSpan) {
    throw new Error('No root agent_run span found in trace');
  }

  return { spanTree, rootAgentSpan };
}

export function transformTraceToScorerInputAndOutput(trace: TraceRecord): {
  input: ScorerRunInputForAgent;
  output: ScorerRunOutputForAgent;
} {
  const { spanTree, rootAgentSpan } = prepareTraceForTransformation(trace);

  if (!rootAgentSpan.output) {
    throw new Error('Root agent span has no output');
  }

  // Build input
  const primaryLLMSpan = findPrimaryLLMSpan(spanTree, rootAgentSpan);
  const inputMessages = extractInputMessages(rootAgentSpan);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Score only traces originating from agent runs (verify root span type before scoring)
2. Align @mastra/core and any instrumentation/tracing package versions so span hierarchy matches
3. Check the traceId — fetch and inspect the trace to confirm it is the intended agent run

Example fix

// before
scoreTrace({ trace: workflowTrace });
// after
if (!getTraceRoots(workflowTrace).some(s => s.spanType === 'agent_run')) skipScoring(workflowTrace.traceId);
else scoreTrace({ trace: workflowTrace });

const roots = buildSpanTree(trace.spans).rootSpans;
if (!roots.some(s => s.spanType === 'agent_run')) throw new Error('Trace is not an agent run');

function isAgentRunTrace(t: TraceRecord): boolean {
  return buildSpanTree(t.spans).rootSpans.some(s => s.spanType === 'agent_run');
}

try {
  prepareTraceForTransformation(trace);
} catch (e) {
  if (e instanceof Error && e.message === 'No root agent_run span found in trace') {
    logger.warn('Skipping scoring: not an agent-run trace', { traceId: trace.traceId });
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Factory kickoff is waiting on a run that has not ended.
• Factory kickoff run terminal event was not observed before t
• Factory kickoff run ended in error.
• Trace is null or undefined
• Trace must have a spans array

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