mastra-ai/mastra · error · MastraError

OBSERVABILITY_UPDATE_SPAN_NOT_FOUND

OBSERVABILITY_UPDATE_SPAN_NOT_FOUND

Error message

Trace not found for span update

What it means

updateSpan looks up the parent trace by traceId before applying updates to a span. If no trace entry exists for that traceId in the in-memory store, it throws this error rather than silently dropping the update — the span's trace was never created or has been evicted.

Source

Thrown at packages/core/src/storage/domains/observability/inmemory.ts:1079

      for (const tag of filters.tags) {
        if (!span.tags.includes(tag)) return false;
      }
    }

    if (filters.status !== undefined) {
      const spanStatus = toTraceSpan(span).status;
      if (spanStatus !== filters.status) return false;
    }

    return true;
  }

  async updateSpan(args: UpdateSpanArgs): Promise<void> {
    const { traceId, spanId, updates } = args;
    const traceEntry = this.db.traces.get(traceId);

    if (!traceEntry) {
      throw new MastraError({
        id: 'OBSERVABILITY_UPDATE_SPAN_NOT_FOUND',
        domain: ErrorDomain.MASTRA_OBSERVABILITY,
        category: ErrorCategory.SYSTEM,
        text: 'Trace not found for span update',
      });
    }

    const span = traceEntry.spans[spanId];
    if (!span) {
      throw new MastraError({
        id: 'OBSERVABILITY_UPDATE_SPAN_NOT_FOUND',
        domain: ErrorDomain.MASTRA_OBSERVABILITY,
        category: ErrorCategory.SYSTEM,
        text: 'Span not found for update',
      });
    }

    const updatedSpan: SpanRecord = {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure the trace is created (createTrace/upserted with its spans) before issuing updateSpan calls.
2. Check ordering: buffer span updates until trace creation is confirmed, or make updates idempotent after re-creating the trace.
3. Verify traceId correctness and that you are querying the same storage instance that holds the trace.
4. For ephemeral in-memory stores, expect state loss on restart — persist traces to a durable provider if updates may outlive the process.

Example fix

// before
await storage.updateSpan({ traceId, spanId, updates }); // trace never created -> throws

// after
await storage.createTrace({ traceId, ... });
await storage.createSpan({ traceId, spanId, ... });
await storage.updateSpan({ traceId, spanId, updates });

const traceExists = storage instanceof ObservabilityInMemory ? (storage as any).db?.traces?.has(traceId) : true;
if (!traceExists) await storage.createTrace({ traceId, ... });

function traceIsKnown(entry: unknown): entry is { traceId: string } {
  return typeof (entry as any)?.traceId === 'string' && (entry as any).traceId.length > 0;
}

try {
  await storage.updateSpan({ traceId, spanId, updates });
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_UPDATE_SPAN_NOT_FOUND') {
    logger.warn(`Trace ${traceId} missing; skipping span update`, { spanId });
  } else throw e;
}

When it happens

Trigger: Calling updateSpan({ traceId, spanId, updates }) where this.db.traces has no entry for traceId (trace never created, already deleted, wrong traceId, or storage restarted losing in-memory state).

Common situations: Updating spans after process restart (in-memory store is empty); spans outliving trace retention/deletion; a race where updates arrive before trace creation completes; passing the wrong id (spanId vs traceId) or trace ids from a different storage backend.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

• Trace not found for scoring, traceId: ${target.traceId}
• Agent with id ${id} not found
• Dataset not found: ${args.id}
• Dataset not found: ${args.datasetId}
• Item not found: ${args.id}

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