mastra-ai/mastra · error · Error

A theme snapshot is required

Error message

A theme snapshot is required

What it means

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.

Source

Thrown at packages/playground-ui/src/ee/signals/hooks/use-theme-flow.ts:22

import type { TraceSignalName } from '../types';
import { useTraceIntelligence } from '../use-trace-intelligence';

export function useThemeFlow(
  entityId: string,
  entityType: string,
  signalNames: TraceSignalName[],
  snapshotId: string | undefined,
) {
  const { cacheScope, request } = useTraceIntelligence();
  return useQuery({
    queryKey: ['entity-learning', cacheScope, entityType, entityId, 'theme-flow', signalNames, snapshotId],
    queryFn: () => fetchThemeFlow(request, entityId, entityType, signalNames, requireSnapshot(snapshotId)),
    enabled: signalNames.length >= 2 && snapshotId !== undefined,
  });
}

function requireSnapshot(snapshotId: string | undefined) {
  if (!snapshotId) throw new Error('A theme snapshot is required');
  return snapshotId;
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure a snapshotId exists (select a default snapshot) before the theme-flow query runs or refetches.
2. Keep enabled: signalNames.length >= 2 && snapshotId !== undefined intact.
3. Include the concrete snapshotId in invalidation/refetch query keys so incomplete queries are not matched.
4. Render a selection prompt/loading state instead of mounting the hook when no snapshot is chosen.

Example fix

// before
queryClient.refetchQueries({ queryKey: ['theme-flow'] });

// after
if (snapshotId && signalNames.length >= 2) {
  queryClient.refetchQueries({ queryKey: ['theme-flow', cacheScope, entityType, entityId, signalNames, snapshotId] });
}

if (signalNames.length >= 2 && snapshotId) {
  queryClient.refetchQueries({ queryKey: ['theme-flow', cacheScope, entityType, entityId, signalNames, snapshotId] });
}

function hasSnapshot(snapshotId: string | undefined): snapshotId is string {
  return typeof snapshotId === 'string' && snapshotId.length > 0;
}

try {
  const flow = await queryClient.fetchQuery({ queryKey, queryFn });
} catch (e) {
  if (e instanceof Error && e.message === 'A theme snapshot is required') {
    // show snapshot selector; do not blind-retry
  }
}

When it happens

Trigger: 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.

Common situations: Snapshot cleared on entity switch while flow chart refetches; deep link without snapshot id; invalidation patterns matching queries without snapshot in the key.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Noise example queries require a trace signal and snapshot
• Noise queries require a trace signal and snapshot
• A numeric theme id is required
• A theme snapshot is required
• Factory project is required

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/9f3e0551aa55445b. Report an issue: GitHub.