{"record":{"id":"566d3e717d38238a","repo":"mastra-ai/mastra","slug":"observability-span-id-required","errorCode":"OBSERVABILITY_SPAN_ID_REQUIRED","errorMessage":"Span ID is required for creating a span","messagePattern":"Span ID is required for creating a span","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"packages/core/src/storage/domains/observability/inmemory.ts","lineNumber":468,"sourceCode":"    this.upsertSpanToTrace(record);\n  }\n\n  async batchCreateSpans(args: BatchCreateSpansArgs): Promise<void> {\n    const now = new Date();\n    for (const span of args.records) {\n      this.validateCreateSpan(span);\n      const record: SpanRecord = {\n        ...span,\n        createdAt: now,\n        updatedAt: now,\n      };\n      this.upsertSpanToTrace(record);\n    }\n  }\n\n  private validateCreateSpan(record: CreateSpanRecord): void {\n    if (!record.spanId) {\n      throw new MastraError({\n        id: 'OBSERVABILITY_SPAN_ID_REQUIRED',\n        domain: ErrorDomain.MASTRA_OBSERVABILITY,\n        category: ErrorCategory.SYSTEM,\n        text: 'Span ID is required for creating a span',\n      });\n    }\n\n    if (!record.traceId) {\n      throw new MastraError({\n        id: 'OBSERVABILITY_TRACE_ID_REQUIRED',\n        domain: ErrorDomain.MASTRA_OBSERVABILITY,\n        category: ErrorCategory.SYSTEM,\n        text: 'Trace ID is required for creating a span',\n      });\n    }\n  }\n\n  /**","sourceCodeStart":450,"sourceCodeEnd":486,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/observability/inmemory.ts#L450-L486","documentation":"validateCreateSpan enforces that every span record persisted to the in-memory observability store carries a spanId; spans without one cannot be keyed inside their trace. createSpan and batchCreateSpans throw this SYSTEM-category error when record.spanId is falsy.","triggerScenarios":"Calling createSpan or batchCreateSpans with a CreateSpanRecord lacking spanId (undefined, null, or empty string).","commonSituations":"Mapping external tracing data (OTel, custom tracers) where the span id field has a different name; dropping fields during serialization; constructing spans manually in tests; a tracer bug emitting spans before assigning ids.","solutions":["Populate spanId on every span before calling createSpan/batchCreateSpans (e.g. crypto.randomUUID()).","When importing from another tracing system, map its span-id field to spanId explicitly.","Filter or fix records missing spanId before batch submission instead of letting one bad record abort the batch.","Verify the span object is not being spread from a source that omits/span-renames the id."],"exampleFix":"// before\nawait storage.createSpan({ traceId, name: 'llm-call' }); // throws\n\n// after\nawait storage.createSpan({ traceId, spanId: crypto.randomUUID(), name: 'llm-call' });","handlingStrategy":"validation","validationCode":"function assertSpanRecord(r: CreateSpanRecord): void {\n  if (!r.spanId) throw new Error('spanId is required');\n  if (!r.traceId) throw new Error('traceId is required');\n}\nspans.forEach(assertSpanRecord);\nawait storage.batchCreateSpans(spans);","typeGuard":"function isCreateableSpan(r: CreateSpanRecord): r is CreateSpanRecord & { spanId: string; traceId: string } {\n  return Boolean(r.spanId) && Boolean(r.traceId);\n}","tryCatchPattern":"try {\n  await storage.createSpan(record);\n} catch (e) {\n  if ((e as MastraError).id === 'OBSERVABILITY_SPAN_ID_REQUIRED') {\n    logger.error('Span dropped: missing spanId', record);\n  } else throw e;\n}","preventionTips":["Generate spanId at span creation time, before any async work.","Map external tracer id fields (e.g. OTel spanContext().spanId) to spanId explicitly.","Filter invalid records out of batches before submission.","Type spans with a branded required-id type in your tracer wrapper."],"tags":["storage","observability","tracing","missing-id"],"backgroundTag":"missing-required-field","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}