{"record":{"id":"1b7c370ee1d97d9a","repo":"mastra-ai/mastra","slug":"observability-trace-id-required","errorCode":"OBSERVABILITY_TRACE_ID_REQUIRED","errorMessage":"Trace ID is required for creating a span","messagePattern":"Trace 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":477,"sourceCode":"        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  /**\n   * Inserts or updates a span in the trace and recomputes trace-level properties\n   */\n  private upsertSpanToTrace(span: SpanRecord): void {\n    const { traceId, spanId } = span;\n    let traceEntry = this.db.traces.get(traceId);\n\n    if (!traceEntry) {\n      traceEntry = {\n        spans: {},","sourceCodeStart":459,"sourceCodeEnd":495,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/storage/domains/observability/inmemory.ts#L459-L495","documentation":"validateCreateSpan also requires traceId: a span must belong to a trace so the store can upsert it into the trace entry. createSpan and batchCreateSpans throw this SYSTEM-category error when record.traceId is falsy.","triggerScenarios":"Calling createSpan or batchCreateSpans with a record missing traceId — e.g. creating a root span without establishing/propagating its trace context.","commonSituations":"Starting spans outside a trace context (no active trace); losing traceId when spans cross async boundaries or serialization; a tracer integration not propagating trace context; manual span construction in tests.","solutions":["Create spans within an active trace or explicitly set traceId (use the trace's id, or create the trace first via createTrace).","Propagate trace context through async boundaries (AsyncLocalStorage / context carriers) so spans inherit traceId.","Fix field mapping when importing spans from other tracers so traceId is preserved.","Validate span records for both traceId and spanId before batch submission."],"exampleFix":"// before\nawait storage.createSpan({ spanId, name: 'tool-call' }); // throws\n\n// after\nawait storage.createSpan({ traceId: activeTrace.id, spanId, name: 'tool-call' });","handlingStrategy":"validation","validationCode":"if (!activeTrace?.id) throw new Error('Cannot create span outside a trace');\nawait storage.createSpan({ traceId: activeTrace.id, spanId, ... });","typeGuard":"function isSpanInTrace(r: CreateSpanRecord): r is CreateSpanRecord & { traceId: string } {\n  return typeof r.traceId === 'string' && r.traceId.length > 0;\n}","tryCatchPattern":"try {\n  await storage.createSpan(record);\n} catch (e) {\n  if ((e as MastraError).id === 'OBSERVABILITY_TRACE_ID_REQUIRED') {\n    logger.error('Span dropped: no trace context', record);\n  } else throw e;\n}","preventionTips":["Only create spans inside an active trace context; create the trace first if needed.","Propagate trace context across async boundaries (AsyncLocalStorage or explicit carriers).","Verify tracer integrations preserve traceId when spans are serialized.","Validate both traceId and spanId before batch span submission."],"tags":["storage","observability","tracing","missing-id","trace-context"],"backgroundTag":"missing-required-field","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}