mastra-ai/mastra · error · Error

Trace ID is required

Error message

Trace ID is required

What it means

useTraceSpans fetches the full trace span tree via client.getTrace(traceId) inside React Query. It throws 'Trace ID is required' when traceId is falsy, converting a missing input into a query error rather than making a malformed request. Callers (traceQuery, traceSpans) inherit this error when they render with no id.

Source

Thrown at packages/playground-ui/src/domains/traces/hooks/use-trace-spans.ts:27

/**
 * Every span of a single trace, with its full payload.
 *
 * The lightweight projection exists to keep blob columns off the read path of a
 * *list*, where the cost is paid once per trace on screen. A trace that is open
 * has already narrowed that to one, and the panel both renders and searches
 * these spans -- `input`, `output` and `attributes` included -- so the
 * projection would only hide content the reader is looking at.
 */
export function useTraceSpans(
  traceId: string | null | undefined,
): UseQueryResult<{ traceId: string; spans: SearchableSpan[] } | null> {
  const client = useMastraClient();

  return useQuery({
    queryKey: ['trace-spans', traceId],
    queryFn: async () => {
      if (!traceId) {
        throw new Error('Trace ID is required');
      }
      const res = await client.getTrace(traceId);
      return res;
    },
    // Builds each span's search haystack once per fetch, cached with the query.
    select: selectSearchableSpans,
    enabled: !!traceId,
    staleTime: query => {
      const data = query.state.data;
      const isFinished = data?.spans.every(span => Boolean(span.endedAt));
      return isFinished ? IMMUTABLE_CACHE_TIME : 0;
    },
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Guard the render site: only mount the component/hook consumer when traceId is truthy.
2. Prefer adding `enabled: !!traceId` to the useQuery call if you can modify the hook.
3. Check where traceId originates (useParams/useSearchParams/selected row) and ensure a default or early return handles the empty case.
4. Inspect React Query devtools to confirm the ['trace-spans', traceId] key and reset the query once a valid id appears.

Example fix

// before
const spans = useTraceSpans(idFromRoute); // possibly undefined
// after
const spans = useTraceSpans(idFromRoute);
if (spans.error) return <TraceError missingId={!idFromRoute} />; // or gate render:
// if (!idFromRoute) return null;

if (typeof traceId !== 'string' || traceId.length === 0) {
  return <TraceNotSelected />; // never call useTraceSpans without an id
}
const { data } = useTraceSpans(traceId);

function isTraceId(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

const q = useTraceSpans(traceId);
if (q.error) {
  if (!traceId) return <EmptyState />; // precondition failure, not a server error
  return <RetryPanel error={q.error} onRetry={q.refetch} />;
}

When it happens

Trigger: Invoking useTraceSpans(undefined), useTraceSpans(null), or useTraceSpans('') because the trace identifier hasn't resolved at render time (route param pending, selection cleared, async lookup not finished).

Common situations: Trace detail view mounted from a stale/deep link with a missing id; a parent renders the spans table while traceId is still being derived from a search-parameter transition; shared component used with an optional traceId prop.

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

• Trace ID is required
• traceId and spanId are required
• Trace ID and Span ID are required
• Session settings are unavailable
• Failed to load models (${res.status})

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