mastra-ai/mastra · error · Error

A numeric theme id is required

Error message

A numeric theme id is required

What it means

requireNumericThemeId validates that a theme id exists and consists only of digits (/^\d+$/). The signals theme hooks (useThemeDetail, useThemeExamples, useThemeHistory) call it inside their query functions because the theme API only accepts numeric theme ids; a missing, empty, or non-numeric id (e.g., a slug or undefined while data loads) throws this error.

Source

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

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. Ensure a numeric theme id is resolved (from route params or parent query) before enabling the query — gate with the hook's enabled option.
2. Convert or look up the id to its numeric form before calling the hook.
3. Validate the id with isNumericThemeId in the calling component and render a loading/error state when it fails.
4. Fix the data source returning non-numeric ids (e.g., strip prefixes or map slug → numeric id).

Example fix

// before
const { data } = useThemeDetail(themeId); // throws when themeId is 'theme-42'

// after
const numericId = /^\d+$/.test(themeId ?? '') ? themeId : undefined;
const { data } = useThemeDetail(numericId, { enabled: numericId !== undefined });

const isNumeric = (id: string | undefined) => id !== undefined && /^\d+$/.test(id);
if (!isNumeric(themeId)) return <ThemeIdMissing />; // skip the query

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

try {
  const id = requireNumericThemeId(routeParams.themeId);
  // proceed with query
} catch {
  // show 'select a valid theme' empty state
}

When it happens

Trigger: Calling useThemeDetail/useThemeExamples/useThemeHistory with themeId undefined during route-param loading, or with a non-numeric id such as 'default', a UUID, or a slug; passing a user-supplied string id that includes non-digit characters.

Common situations: Route params not yet parsed when the query runs; theme selected from a list keyed by name rather than numeric id; API change returning string ids with prefixes; stale links containing old id formats.

Related errors

• A theme snapshot 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/4d1332f60fa82b07. Report an issue: GitHub.