mastra-ai/mastra · error · Error

A theme snapshot is required

Error message

A theme snapshot is required

What it means

requireSnapshotId ensures a theme snapshot id is present before a theme query executes. Snapshot-dependent hooks (useThemeDetail, useThemeExamples, useThemePaths) call it because the API needs a specific snapshot to fetch against; when snapshotId is undefined or empty (typically because no snapshot has been selected or loaded yet), the guard throws this error.

Source

Thrown at packages/playground-ui/src/ee/signals/hooks/theme-query-guards.ts:11

export function isNumericThemeId(themeId: string | undefined): themeId is string {
  return themeId !== undefined && /^\d+$/.test(themeId);
}

export function requireNumericThemeId(themeId: string | undefined) {
  if (!isNumericThemeId(themeId)) throw new Error('A numeric theme id is required');
  return themeId;
}

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Gate the query with enabled: snapshotId !== undefined so queryFn never runs without a snapshot.
2. Select a default snapshot before rendering the dependent hooks.
3. Await/loading-gate the snapshot list query and render a loading state until a snapshotId exists.
4. Persist the snapshot id in the URL/store so deep links always provide one.

Example fix

// before
useThemeExamples({ themeId, snapshotId }); // throws when snapshotId undefined

// after
const ready = themeId !== undefined && snapshotId !== undefined;
return ready ? useThemeExamples({ themeId, snapshotId }) : { data: undefined, isLoading: true };

if (!snapshotId) {
  return <SnapshotPicker />; // don't run snapshot-dependent hooks yet
}
const id = requireSnapshotId(snapshotId); // safe

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

try {
  const id = requireSnapshotId(maybeSnapshotId);
  // fetch with id
} catch {
  // prompt the user to select a snapshot
}

When it happens

Trigger: Calling useThemeDetail/useThemeExamples/useThemePaths before a snapshot is chosen; snapshot list query still loading so snapshotId is undefined; a user landing directly on a theme page with no snapshot in the URL or store.

Common situations: First page load before snapshot selection; clearing snapshot state on entity change; deep links missing the snapshot parameter; races between snapshot fetch and dependent queries.

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

• A numeric theme id is required
• Noise example queries require a trace signal and snapshot
• Noise queries require a trace signal and snapshot
• A theme snapshot is required
• Query parameters "versionId" and "status" are mutually exclu

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