{"record":{"id":"82101e497748856c","repo":"mastra-ai/mastra","slug":"span-not-found","errorCode":null,"errorMessage":"Span not found","messagePattern":"Span not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"packages/server/src/server/handlers/observability.ts","lineNumber":347,"sourceCode":"\n/** Route: GET /observability/traces/:traceId/spans/:spanId - get a single span with full details. */\nexport const GET_SPAN_ROUTE: ServerRoute = createRoute({\n  method: 'GET',\n  path: '/observability/traces/:traceId/spans/:spanId',\n  responseType: 'json',\n  pathParamSchema: getSpanArgsSchema,\n  responseSchema: getSpanResponseSchema,\n  summary: 'Get a single span by ID',\n  description: 'Returns a complete span record with all details by trace ID and span ID',\n  tags: ['Observability'],\n  requiresAuth: true,\n  handler: async ({ mastra, traceId, spanId }) => {\n    try {\n      const observabilityStore = await getObservabilityStore(mastra);\n      const span = await observabilityStore.getSpan({ traceId, spanId });\n\n      if (!span) {\n        throw new HTTPException(404, { message: `Span not found` });\n      }\n\n      return span;\n    } catch (error) {\n      return handleError(error, 'Error getting span');\n    }\n  },\n});\n\n/** Route: GET /observability/traces/:traceId/trajectory - extract trajectory from a trace. */\nexport const GET_TRACE_TRAJECTORY_ROUTE = createRoute({\n  method: 'GET',\n  path: '/observability/traces/:traceId/trajectory',\n  responseType: 'json',\n  pathParamSchema: getTraceArgsSchema,\n  responseSchema: z.object({\n    steps: z.array(z.unknown()),\n    totalDurationMs: z.number().optional(),","sourceCodeStart":329,"sourceCodeEnd":365,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/observability.ts#L329-L365","documentation":"The span endpoint resolves a single span via `observabilityStore.getSpan({ traceId, spanId })`; when nothing is returned the handler throws a 404 'Span not found'. Both the trace and the specific span ID must exist in the store.","triggerScenarios":"Calling GET /api/observability/traces/:traceId/spans/:spanId where the spanId doesn't exist under that trace — wrong span ID, span from a different trace, or partial ingestion (trace exists but span wasn't persisted).","commonSituations":"Referencing a span ID from logs of a different trace; storage write failures dropped individual spans; querying in-progress traces before the span was flushed.","solutions":["Fetch the full trace first and pick a spanId from its spans array.","Confirm the spanId belongs to the given traceId (IDs are not globally unique).","Check the storage backend for ingestion gaps or write errors.","Return a graceful 'span unavailable' UI state on 404."],"exampleFix":"// before\nconst span = await fetch(`/api/observability/traces/${traceId}/spans/${spanId}`).then(r => r.json());\n// after\nconst trace = await fetch(`/api/observability/traces/${traceId}`).then(r => r.json());\nconst span = trace.spans.find(s => s.id === spanId);\nif (!span) throw new Error(`Span ${spanId} not in trace ${traceId}`);","handlingStrategy":"validation","validationCode":"const trace = await getTrace(traceId);\nif (!trace.spans.some(s => s.id === spanId)) {\n  throw new Error(`Span ${spanId} not in trace ${traceId}`);\n}","typeGuard":"function hasSpan(trace: { spans: { id: string }[] }, spanId: string): boolean {\n  return trace.spans.some(s => s.id === spanId);\n}","tryCatchPattern":"try {\n  return await getSpan(traceId, spanId);\n} catch (e) {\n  if (is404(e)) return null; // span unavailable\n  throw e;\n}","preventionTips":["Derive spanIds from the trace response rather than external logs.","Remember span IDs are scoped per trace, not globally unique.","Check ingestion health if spans are routinely missing from stored traces."],"tags":["http-404","observability","tracing","spans"],"backgroundTag":"span-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}