mastra-ai/mastra · error · Error

Trace ID is required

Error message

Trace ID is required

What it means

useTraceLightSpans fetches a trace's spans in lightweight form via the Mastra client's getTraceLight API inside a React Query query. The hook deliberately throws 'Trace ID is required' when invoked with a falsy traceId instead of issuing a pointless network request. React Query surfaces this as a failed query (error state), so callers see the error even though it's a local precondition failure.

Source

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

import { useMastraClient } from '@mastra/react';
import { useQuery } from '@tanstack/react-query';
import type { UseQueryResult } from '@tanstack/react-query';
import type { SearchableSpan } from '../types';
import { selectSearchableSpans } from '../utils';

const IMMUTABLE_CACHE_TIME = 1000 * 60 * 60 * 24 * 30; // 30 days, massive cache, span data is immutable

export function useTraceLightSpans(
  traceId: string | null | undefined,
): UseQueryResult<{ traceId: string; spans: SearchableSpan[] } | null> {
  const client = useMastraClient();

  return useQuery({
    queryKey: ['trace-light-spans', traceId],
    queryFn: async () => {
      if (!traceId) {
        throw new Error('Trace ID is required');
      }
      const res = await client.getTraceLight(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(d => Boolean(d.endedAt));

      if (isFinished) {
        return IMMUTABLE_CACHE_TIME;
      }

      return 0;
    },

View on GitHub (pinned to 75dd419e61)

Solutions

1. Enable/guard the query: pass `enabled: !!traceId` is not available on the hook, so only render the hook's consumer (or the hook itself) when traceId is truthy — e.g. wrap usage in a conditional component or early-return before mounting.
2. If you own the hook, add `enabled: Boolean(traceId)` to the useQuery options so the throw never fires.
3. Verify the source of traceId (route params, search params, selection state) actually resolves before render; log it if unsure.
4. If the query already errored, clear the invalid selection and remount with a valid id.

Example fix

// before
const { data } = useTraceLightSpans(traceId); // traceId may be undefined
// after
if (!traceId) return <NoTraceSelected />;
const { data } = useTraceLightSpans(traceId);

if (!traceId) {
  // render empty/placeholder state instead of calling the hook's query
  return <TraceNotSelected />;
}
const { data } = useTraceLightSpans(traceId);

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

const q = useTraceLightSpans(traceId);
if (q.isPending) return <Spinner />;
if (q.error) {
  if (q.error.message === 'Trace ID is required') return <EmptyState />;
  throw q.error; // rethrow unexpected errors
}

When it happens

Trigger: Calling useTraceLightSpans(undefined) or useTraceLightSpans('') — typically because the traceId prop/state hasn't been populated yet (e.g. URL param not yet parsed, trace selected before data arrives).

Common situations: A trace detail page renders before the router supplies the :traceId param; a list-to-detail navigation passes an optimistic/placeholder id; a component is reused for both 'list' and 'detail' modes where traceId is only set in detail mode.

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/bb3d8f44a85a3b87. Report an issue: GitHub.