{"record":{"id":"bb3d8f44a85a3b87","repo":"mastra-ai/mastra","slug":"trace-id-is-required","errorCode":null,"errorMessage":"Trace ID is required","messagePattern":"Trace ID is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playground-ui/src/domains/traces/hooks/use-trace-light-spans.ts","lineNumber":18,"sourceCode":"import { useMastraClient } from '@mastra/react';\nimport { useQuery } from '@tanstack/react-query';\nimport type { UseQueryResult } from '@tanstack/react-query';\nimport type { SearchableSpan } from '../types';\nimport { selectSearchableSpans } from '../utils';\n\nconst IMMUTABLE_CACHE_TIME = 1000 * 60 * 60 * 24 * 30; // 30 days, massive cache, span data is immutable\n\nexport function useTraceLightSpans(\n  traceId: string | null | undefined,\n): UseQueryResult<{ traceId: string; spans: SearchableSpan[] } | null> {\n  const client = useMastraClient();\n\n  return useQuery({\n    queryKey: ['trace-light-spans', traceId],\n    queryFn: async () => {\n      if (!traceId) {\n        throw new Error('Trace ID is required');\n      }\n      const res = await client.getTraceLight(traceId);\n      return res;\n    },\n    // Builds each span's search haystack once per fetch, cached with the query.\n    select: selectSearchableSpans,\n    enabled: !!traceId,\n    staleTime: query => {\n      const data = query.state.data;\n\n      const isFinished = data?.spans.every(d => Boolean(d.endedAt));\n\n      if (isFinished) {\n        return IMMUTABLE_CACHE_TIME;\n      }\n\n      return 0;\n    },","sourceCodeStart":1,"sourceCodeEnd":36,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/playground-ui/src/domains/traces/hooks/use-trace-light-spans.ts#L1-L36","documentation":"useTraceLightSpans fetches a trace's spans in lightweight form via the Mastra client's getTraceLight API inside a React Query query. The hook deliberately throws 'Trace ID is required' when invoked with a falsy traceId instead of issuing a pointless network request. React Query surfaces this as a failed query (error state), so callers see the error even though it's a local precondition failure.","triggerScenarios":"Calling useTraceLightSpans(undefined) or useTraceLightSpans('') — typically because the traceId prop/state hasn't been populated yet (e.g. URL param not yet parsed, trace selected before data arrives).","commonSituations":"A trace detail page renders before the router supplies the :traceId param; a list-to-detail navigation passes an optimistic/placeholder id; a component is reused for both 'list' and 'detail' modes where traceId is only set in detail mode.","solutions":["Enable/guard the query: pass `enabled: !!traceId` is not available on the hook, so only render the hook's consumer (or the hook itself) when traceId is truthy — e.g. wrap usage in a conditional component or early-return before mounting.","If you own the hook, add `enabled: Boolean(traceId)` to the useQuery options so the throw never fires.","Verify the source of traceId (route params, search params, selection state) actually resolves before render; log it if unsure.","If the query already errored, clear the invalid selection and remount with a valid id."],"exampleFix":"// before\nconst { data } = useTraceLightSpans(traceId); // traceId may be undefined\n// after\nif (!traceId) return <NoTraceSelected />;\nconst { data } = useTraceLightSpans(traceId);","handlingStrategy":"validation","validationCode":"if (!traceId) {\n  // render empty/placeholder state instead of calling the hook's query\n  return <TraceNotSelected />;\n}\nconst { data } = useTraceLightSpans(traceId);","typeGuard":"function hasTraceId(id: string | undefined | null): id is string {\n  return typeof id === 'string' && id.length > 0;\n}","tryCatchPattern":"const q = useTraceLightSpans(traceId);\nif (q.isPending) return <Spinner />;\nif (q.error) {\n  if (q.error.message === 'Trace ID is required') return <EmptyState />;\n  throw q.error; // rethrow unexpected errors\n}","preventionTips":["Gate rendering of trace-dependent components on a truthy traceId.","Prefer `enabled: !!traceId` in useQuery options when you control the hook.","Derive traceId from typed route params with a schema validation layer.","Check React Query devtools to confirm the query key before debugging fetches."],"tags":["react-query","precondition","traces","playground-ui"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}