mastra-ai/mastra · warning · HTTPException

Trace with ID '${traceId}' not found

Error message

Trace with ID '${traceId}' not found

What it means

The GET trace-by-ID handler in the observability server looks up the trace in the configured observability storage via `observabilityStore.getTrace({ traceId })`. When the store returns no record, the handler throws a 404 HTTPException with the trace ID interpolated. This means the request itself is valid but no trace with that ID exists in storage.

Source

Thrown at packages/server/src/server/handlers/observability.ts:290

});
/** Route: GET /observability/traces/:traceId - retrieve a single trace with all spans. */
export const GET_TRACE_ROUTE: ServerRoute = createRoute({
  method: 'GET',
  path: '/observability/traces/:traceId',
  responseType: 'json',
  pathParamSchema: getTraceArgsSchema,
  responseSchema: getTraceResponseSchema.extend({ spans: z.array(traceSpanSchema) }),
  summary: 'Get AI trace by ID',
  description: 'Returns a complete AI trace with all spans by trace ID',
  tags: ['Observability'],
  requiresAuth: true,
  handler: async ({ mastra, traceId }) => {
    try {
      const observabilityStore = await getObservabilityStore(mastra);
      const trace = await observabilityStore.getTrace({ traceId });

      if (!trace) {
        throw new HTTPException(404, { message: `Trace with ID '${traceId}' not found` });
      }

      // Stored SpanRecords carry no status field; derive it from error/endedAt so
      // trace-detail spans match the status shown in trace list rows.
      return { ...trace, spans: toTraceSpans(trace.spans) };
    } catch (error) {
      return handleError(error, 'Error getting trace');
    }
  },
});

/** Route: GET /observability/traces/:traceId/light - lightweight trace for timeline rendering. */
export const GET_TRACE_LIGHT_ROUTE: ServerRoute = createRoute({
  method: 'GET',
  path: '/observability/traces/:traceId/light',
  responseType: 'json',
  pathParamSchema: getTraceArgsSchema,
  responseSchema: getTraceLightResponseSchema,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the traceId by listing traces first (GET /api/observability/traces) and using an ID from the list response.
2. Confirm the Mastra instance's storage/observability configuration points at the same database where the trace was recorded.
3. Check retention/TTL settings to ensure the trace hasn't been purged.
4. Handle the 404 in the client and show a 'trace not found' state instead of retrying.

Example fix

// before
const trace = await fetch(`/api/observability/traces/${id}`).then(r => r.json());
// after
const res = await fetch(`/api/observability/traces/${id}`);
if (res.status === 404) {
  throw new Error(`Trace ${id} not found in storage`);
}
const trace = await res.json();

const list = await fetch('/api/observability/traces').then(r => r.json());
const exists = list.traces?.some(t => t.traceId === traceId);
if (!exists) throw new Error(`Trace ${traceId} not in store`);

function isTrace(t: unknown): t is { traceId: string; spans: unknown[] } {
  return !!t && typeof t === 'object' && 'traceId' in t && 'spans' in t;
}

try {
  const trace = await getTrace(traceId);
} catch (e) {
  if (e.status === 404 || /not found/i.test(e.message)) {
    return null; // render 'trace not found' state
  }
  throw e;
}

When it happens

Trigger: Calling GET /api/observability/traces/:traceId with a traceId that is not present in the observability store — deleted traces, expired/retention-purged traces, traces stored in a different storage backend, or a typo'd/copied-wrong ID.

Common situations: Pointing the server at a different storage database than the one that recorded the trace; retention cleanup removed old traces; fetching a trace from a sample/mock ID; copy-pasting a span ID instead of a trace ID.

Related errors

• Trace not found for scoring, traceId: ${target.traceId}
• OBSERVABILITY_CREATE_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_UPDATE_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_ROOT_SPAN_NOT_IMPLEMENTED

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