mastra-ai/mastra · error · Error

Trace must have a spans array

Error message

Trace must have a spans array

What it means

validateTrace throws this when `trace.spans` is missing or not an array. A TraceRecord without a valid spans array cannot be traversed to build the span tree used for extracting scorer input/output.

Source

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

    toolCallId: toolSpan.spanId,
    toolName: toolSpan.entityName ?? toolSpan.entityId ?? 'unknown',
    toolId: toolSpan.entityId,
    args: toolSpan.input || {},
    result: toolSpan.output || {},
    state: 'result' as const,
  }));
}

/**
 * Validate trace structure and throw descriptive errors
 */
export function validateTrace(trace: TraceRecord): void {
  if (!trace) {
    throw new Error('Trace is null or undefined');
  }

  if (!trace.spans || !Array.isArray(trace.spans)) {
    throw new Error('Trace must have a spans array');
  }

  if (trace.spans.length === 0) {
    throw new Error('Trace has no spans');
  }

  // Check for circular references in parent-child relationships
  const spanIds = new Set(trace.spans.map(span => span.spanId));
  for (const span of trace.spans) {
    if (span.parentSpanId && !spanIds.has(span.parentSpanId)) {
      throw new Error(`Span ${span.spanId} references non-existent parent ${span.parentSpanId}`);
    }
  }
}

/**
 * Find the most recent model span that contains conversation history
 */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the trace was fully persisted (spans included) in the observability storage before scoring
2. Re-check the storage adapter's trace serialization/deserialization to ensure spans survive round-trips
3. Validate the record shape (Array.isArray(trace.spans)) before calling the transformation

Example fix

// before
transformTraceToScorerInputAndOutput(maybeTrace);
// after
if (!maybeTrace || !Array.isArray(maybeTrace.spans)) throw new Error('Invalid trace record');
transformTraceToScorerInputAndOutput(maybeTrace);

if (!trace || !Array.isArray(trace.spans)) {
  throw new Error('Trace record is malformed: spans array missing');
}

function hasSpansArray(t: unknown): t is TraceRecord & { spans: unknown[] } {
  return typeof t === 'object' && t !== null && Array.isArray((t as TraceRecord).spans);
}

try {
  transformTraceToScorerInputAndOutput(trace);
} catch (e) {
  if (e instanceof Error && e.message === 'Trace must have a spans array') {
    logger.warn('Malformed trace record; skipping scoring', { traceId: trace?.traceId });
  } else throw e;
}

When it happens

Trigger: A trace record fetched from storage has no spans field (e.g. only metadata was persisted, or a hand-constructed/malformed TraceRecord object is passed to the transformation helpers).

Common situations: Partially ingested traces; custom storage adapters that serialize traces incorrectly (dropping spans); passing an object of the wrong shape (TS unchecked, e.g. from JSON) into the scoring pipeline.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Trace is null or undefined
• Trace has no spans
• No model generation span found in trace
• Root agent span has no output
• Plugin tool "${name}" must be an object with a tool property

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