{"record":{"id":"9d8429ab82bdc92b","repo":"mastra-ai/mastra","slug":"span-span-spanid-references-non-existent-parent","errorCode":null,"errorMessage":"Span ${span.spanId} references non-existent parent ${span.parentSpanId}","messagePattern":"Span (.+?) references non-existent parent (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/core/src/evals/scoreTraces/utils.ts","lineNumber":232,"sourceCode":" */\nexport function validateTrace(trace: TraceRecord): void {\n  if (!trace) {\n    throw new Error('Trace is null or undefined');\n  }\n\n  if (!trace.spans || !Array.isArray(trace.spans)) {\n    throw new Error('Trace must have a spans array');\n  }\n\n  if (trace.spans.length === 0) {\n    throw new Error('Trace has no spans');\n  }\n\n  // Check for circular references in parent-child relationships\n  const spanIds = new Set(trace.spans.map(span => span.spanId));\n  for (const span of trace.spans) {\n    if (span.parentSpanId && !spanIds.has(span.parentSpanId)) {\n      throw new Error(`Span ${span.spanId} references non-existent parent ${span.parentSpanId}`);\n    }\n  }\n}\n\n/**\n * Find the most recent model span that contains conversation history\n */\nfunction findPrimaryLLMSpan(spanTree: SpanTree, rootAgentSpan: SpanRecord): SpanRecord {\n  const directLLMSpans = getChildrenOfType<SpanRecord>(spanTree, rootAgentSpan.spanId, SpanType.MODEL_GENERATION);\n  if (directLLMSpans.length > 0) {\n    // 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/**","sourceCodeStart":214,"sourceCodeEnd":250,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/evals/scoreTraces/utils.ts#L214-L250","documentation":"validateTrace rejects traces where a span's parentSpanId points to a spanId not present in the trace. The parent-child span tree would be broken, so the throw prevents incorrect scorer input extraction from an inconsistent hierarchy.","triggerScenarios":"A span in trace.spans has a non-null parentSpanId that no other span in the array contains — e.g. partial span ingestion (parent dropped by retention/sampling), spans imported from another trace, or manually assembled trace data.","commonSituations":"Retention or sampling policies dropping some spans while keeping children; custom instrumentation creating spans with mismatched parent IDs; cross-trace span copying during debugging tooling.","solutions":["Persist/retain complete span sets so parents and children are always ingested together","Fix instrumentation so child spans reference parents within the same trace","Orphan-check/repair the trace (attach orphan spans to root or drop them) before scoring"],"exampleFix":"// before\nspans = allSpans; // some parents missing\n// after\nconst ids = new Set(allSpans.map(s => s.spanId));\nspans = allSpans.filter(s => !s.parentSpanId || ids.has(s.parentSpanId));","handlingStrategy":"validation","validationCode":"const ids = new Set(trace.spans.map(s => s.spanId));\nconst orphans = trace.spans.filter(s => s.parentSpanId && !ids.has(s.parentSpanId));\nif (orphans.length) throw new Error(`Orphan spans: ${orphans.map(s => s.spanId).join(',')}`);","typeGuard":"function hasConsistentParents(t: TraceRecord): boolean {\n  const ids = new Set(t.spans.map(s => s.spanId));\n  return t.spans.every(s => !s.parentSpanId || ids.has(s.parentSpanId));\n}","tryCatchPattern":"try {\n  transformTraceToScorerInputAndOutput(trace);\n} catch (e) {\n  if (e instanceof Error && /references non-existent parent/.test(e.message)) {\n    logger.warn('Trace has orphan spans; repairing before scoring');\n  } else throw e;\n}","preventionTips":["Ensure span sampling/retention keeps parents with children","Validate parent IDs at span creation time in custom instrumentation","Repair or drop orphan spans before scoring","Keep trace data within a single trace — never copy spans across traces"],"tags":["trace","span-tree","data-integrity"],"backgroundTag":"orphan-span-parent-missing","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}