{"record":{"id":"0758789601ba6e39","repo":"mastra-ai/mastra","slug":"traceid-and-spanid-are-required","errorCode":null,"errorMessage":"traceId and spanId are required","messagePattern":"traceId and spanId are required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"warning","filePath":"packages/playground-ui/src/domains/traces/hooks/use-branch.ts","lineNumber":26,"sourceCode":"\nexport interface UseBranchArgs {\n  traceId: string | null | undefined;\n  spanId: string | null | undefined;\n  depth?: number;\n}\n\nexport function useBranch({\n  traceId,\n  spanId,\n  depth,\n}: UseBranchArgs): UseQueryResult<{ traceId: string; spans: SearchableSpan[] } | null> {\n  const client = useMastraClient();\n\n  return useQuery({\n    queryKey: ['branch', traceId, spanId, depth],\n    queryFn: async () => {\n      if (!traceId || !spanId) {\n        throw new Error('traceId and spanId are required');\n      }\n      return client.getBranch({ traceId, spanId, depth });\n    },\n    // Builds each span's search haystack once per fetch, cached with the query.\n    select: selectSearchableSpans,\n    enabled: !!traceId && !!spanId,\n    staleTime: query => {\n      const data = query.state.data;\n      const isFinished = data?.spans.every(s => Boolean(s.endedAt));\n      return isFinished ? IMMUTABLE_CACHE_TIME : 0;\n    },\n  });\n}\n","sourceCodeStart":8,"sourceCodeEnd":40,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/playground-ui/src/domains/traces/hooks/use-branch.ts#L8-L40","documentation":"React Query queryFn for the branch query in the playground UI requires both traceId and spanId to fetch a span's branch, and throws this error when either is missing. In practice the query is disabled (enabled: !!traceId && !!spanId) so this only fires if the query is forced to run with undefined IDs.","triggerScenarios":"Manually triggering/refetching the ['branch'] query with undefined traceId or spanId; rendering a component that calls useBranch before IDs resolve and forcing an immediate refetch; calling branchQuery directly in tests without arguments.","commonSituations":"Deep-linking to a span detail view where URL params are not yet parsed; trace data still loading so IDs are undefined; custom queryClient.fetchQuery calls that skip the enabled guard.","solutions":["Wait for traceId/spanId to be defined before mounting/refetching (the hook already disables the query when either is falsy).","If using queryClient.fetchQuery manually, check both IDs before invoking.","Fix URL/route parsing so trace and span IDs are extracted before the hook runs.","Render the branch view only after the parent trace/span selection resolves (conditional rendering)."],"exampleFix":"// before\nconst { data } = useBranch(undefined, spanId);\n// after\nconst { data } = traceId && spanId ? useBranch(traceId, spanId) : { data: undefined };","handlingStrategy":"validation","validationCode":"if (!traceId || !spanId) return null; // skip branch fetch until both IDs exist\nconst branch = await queryClient.fetchQuery({\n  queryKey: ['branch', traceId, spanId, depth],\n  queryFn: () => client.getBranch({ traceId, spanId, depth }),\n});","typeGuard":"const hasTraceSpan = (v: { traceId?: string; spanId?: string }): v is { traceId: string; spanId: string } =>\n  typeof v.traceId === 'string' && v.traceId.length > 0 && typeof v.spanId === 'string' && v.spanId.length > 0;","tryCatchPattern":"try {\n  const data = await queryClient.fetchQuery({ queryKey: ['branch', traceId, spanId, depth], queryFn });\n} catch (e) {\n  if (e instanceof Error && e.message === 'traceId and spanId are required') return null;\n  throw e;\n}","preventionTips":["Rely on the hook's enabled guard; avoid manual refetch before IDs resolve.","Conditionally render the branch component only after a span is selected.","Parse route/search params with a schema (e.g. zod) so IDs are typed as present.","In tests, pass explicit IDs rather than relying on ambient state."],"tags":["react","react-query","traces","missing-argument","playground-ui"],"backgroundTag":"missing-required-identifier","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}