{"record":{"id":"1bdd5d0ca6cab754","repo":"mastra-ai/mastra","slug":"trace-with-id-traceid-not-found","errorCode":null,"errorMessage":"Trace with ID '${traceId}' not found","messagePattern":"Trace with ID '(.+?)' not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"packages/server/src/server/handlers/observability.ts","lineNumber":290,"sourceCode":"});\n/** Route: GET /observability/traces/:traceId - retrieve a single trace with all spans. */\nexport const GET_TRACE_ROUTE: ServerRoute = createRoute({\n  method: 'GET',\n  path: '/observability/traces/:traceId',\n  responseType: 'json',\n  pathParamSchema: getTraceArgsSchema,\n  responseSchema: getTraceResponseSchema.extend({ spans: z.array(traceSpanSchema) }),\n  summary: 'Get AI trace by ID',\n  description: 'Returns a complete AI trace with all spans by trace ID',\n  tags: ['Observability'],\n  requiresAuth: true,\n  handler: async ({ mastra, traceId }) => {\n    try {\n      const observabilityStore = await getObservabilityStore(mastra);\n      const trace = await observabilityStore.getTrace({ traceId });\n\n      if (!trace) {\n        throw new HTTPException(404, { message: `Trace with ID '${traceId}' not found` });\n      }\n\n      // Stored SpanRecords carry no status field; derive it from error/endedAt so\n      // trace-detail spans match the status shown in trace list rows.\n      return { ...trace, spans: toTraceSpans(trace.spans) };\n    } catch (error) {\n      return handleError(error, 'Error getting trace');\n    }\n  },\n});\n\n/** Route: GET /observability/traces/:traceId/light - lightweight trace for timeline rendering. */\nexport const GET_TRACE_LIGHT_ROUTE: ServerRoute = createRoute({\n  method: 'GET',\n  path: '/observability/traces/:traceId/light',\n  responseType: 'json',\n  pathParamSchema: getTraceArgsSchema,\n  responseSchema: getTraceLightResponseSchema,","sourceCodeStart":272,"sourceCodeEnd":308,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/observability.ts#L272-L308","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the traceId by listing traces first (GET /api/observability/traces) and using an ID from the list response.","Confirm the Mastra instance's storage/observability configuration points at the same database where the trace was recorded.","Check retention/TTL settings to ensure the trace hasn't been purged.","Handle the 404 in the client and show a 'trace not found' state instead of retrying."],"exampleFix":"// before\nconst trace = await fetch(`/api/observability/traces/${id}`).then(r => r.json());\n// after\nconst res = await fetch(`/api/observability/traces/${id}`);\nif (res.status === 404) {\n  throw new Error(`Trace ${id} not found in storage`);\n}\nconst trace = await res.json();","handlingStrategy":"try-catch","validationCode":"const list = await fetch('/api/observability/traces').then(r => r.json());\nconst exists = list.traces?.some(t => t.traceId === traceId);\nif (!exists) throw new Error(`Trace ${traceId} not in store`);","typeGuard":"function isTrace(t: unknown): t is { traceId: string; spans: unknown[] } {\n  return !!t && typeof t === 'object' && 'traceId' in t && 'spans' in t;\n}","tryCatchPattern":"try {\n  const trace = await getTrace(traceId);\n} catch (e) {\n  if (e.status === 404 || /not found/i.test(e.message)) {\n    return null; // render 'trace not found' state\n  }\n  throw e;\n}","preventionTips":["Always obtain traceIds from the trace list endpoint, never hand-typed.","Keep client and server storage configs pointing at the same database.","Account for retention windows when fetching old traces."],"tags":["http-404","observability","tracing","storage"],"backgroundTag":"trace-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}