{"record":{"id":"9f3e0551aa55445b","repo":"mastra-ai/mastra","slug":"a-theme-snapshot-is-required-9f3e05","errorCode":null,"errorMessage":"A theme snapshot is required","messagePattern":"A theme snapshot is required","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/playground-ui/src/ee/signals/hooks/use-theme-flow.ts","lineNumber":22,"sourceCode":"import type { TraceSignalName } from '../types';\nimport { useTraceIntelligence } from '../use-trace-intelligence';\n\nexport function useThemeFlow(\n  entityId: string,\n  entityType: string,\n  signalNames: TraceSignalName[],\n  snapshotId: string | undefined,\n) {\n  const { cacheScope, request } = useTraceIntelligence();\n  return useQuery({\n    queryKey: ['entity-learning', cacheScope, entityType, entityId, 'theme-flow', signalNames, snapshotId],\n    queryFn: () => fetchThemeFlow(request, entityId, entityType, signalNames, requireSnapshot(snapshotId)),\n    enabled: signalNames.length >= 2 && snapshotId !== undefined,\n  });\n}\n\nfunction requireSnapshot(snapshotId: string | undefined) {\n  if (!snapshotId) throw new Error('A theme snapshot is required');\n  return snapshotId;\n}\n","sourceCodeStart":4,"sourceCodeEnd":25,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/playground-ui/src/ee/signals/hooks/use-theme-flow.ts#L4-L25","documentation":"useThemeFlow fetches theme flow data for two or more signals against a theme snapshot, calling the local requireSnapshot helper inside its queryFn to convert the possibly-undefined snapshotId into a required string. If snapshotId is absent when the query function executes, this error is thrown. Like its siblings, the query has an enabled guard, so the throw is a defensive invariant against forced executions.","triggerScenarios":"Refetching or imperatively fetching the theme-flow query while snapshotId is undefined; calling useThemeFlow with a snapshot that has not loaded; overriding enabled; tests invoking the queryFn without a snapshot fixture.","commonSituations":"Snapshot cleared on entity switch while flow chart refetches; deep link without snapshot id; invalidation patterns matching queries without snapshot in the key.","solutions":["Ensure a snapshotId exists (select a default snapshot) before the theme-flow query runs or refetches.","Keep enabled: signalNames.length >= 2 && snapshotId !== undefined intact.","Include the concrete snapshotId in invalidation/refetch query keys so incomplete queries are not matched.","Render a selection prompt/loading state instead of mounting the hook when no snapshot is chosen."],"exampleFix":"// before\nqueryClient.refetchQueries({ queryKey: ['theme-flow'] });\n\n// after\nif (snapshotId && signalNames.length >= 2) {\n  queryClient.refetchQueries({ queryKey: ['theme-flow', cacheScope, entityType, entityId, signalNames, snapshotId] });\n}","handlingStrategy":"validation","validationCode":"if (signalNames.length >= 2 && snapshotId) {\n  queryClient.refetchQueries({ queryKey: ['theme-flow', cacheScope, entityType, entityId, signalNames, snapshotId] });\n}","typeGuard":"function hasSnapshot(snapshotId: string | undefined): snapshotId is string {\n  return typeof snapshotId === 'string' && snapshotId.length > 0;\n}","tryCatchPattern":"try {\n  const flow = await queryClient.fetchQuery({ queryKey, queryFn });\n} catch (e) {\n  if (e instanceof Error && e.message === 'A theme snapshot is required') {\n    // show snapshot selector; do not blind-retry\n  }\n}","preventionTips":["Select/persist a snapshot before rendering useThemeFlow.","Preserve the enabled guard requiring snapshotId and at least two signals.","Put snapshotId in the query key so invalidation can't hit incomplete queries.","On entity change, reset snapshot state and dependent queries together."],"tags":["validation","react-query","signals","defensive-check"],"backgroundTag":"missing-required-parameter","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}