mastra-ai/mastra · warning · Error

Trace ID and Span ID are required

Error message

Trace ID and Span ID are required

What it means

The useSpanDetail hook's queryFn validates that both traceId and spanId exist before calling client.getSpan, and throws 'Trace ID and Span ID are required' otherwise. The query is normally disabled until both IDs are truthy, so this surfaces when the query runs without valid IDs.

Source

Thrown at packages/playground-ui/src/domains/traces/hooks/use-span-detail.ts:18

import type { LightSpanRecord } from '@mastra/core/storage';
import { useMastraClient } from '@mastra/react';
import { useQuery } from '@tanstack/react-query';
import type { UseQueryResult } from '@tanstack/react-query';

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

export function useSpanDetail(
  traceId: string | null | undefined,
  spanId: string | null | undefined,
): UseQueryResult<{ span: LightSpanRecord & { output?: unknown; result?: unknown } } | null> {
  const client = useMastraClient();

  return useQuery({
    queryKey: ['span-detail', traceId, spanId],
    queryFn: async () => {
      if (!traceId || !spanId) {
        throw new Error('Trace ID and Span ID are required');
      }
      return client.getSpan(traceId, spanId);
    },
    enabled: !!traceId && !!spanId,
    staleTime: query => {
      const data = query.state.data;

      if (data?.span?.endedAt) {
        return IMMUTABLE_CACHE_TIME;
      }

      return 0;
    },
  });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Gate rendering of the span detail consumer on both IDs being present (the hook's enabled flag already does this for automatic fetching).
2. Before queryClient.fetchQuery/getQueryData-triggered refetches, assert traceId && spanId.
3. Fix prop/route plumbing so traceId and spanId are always the resolved values.
4. Log/inspect the queryKey when it fires to find which ID is undefined.

Example fix

// before
refetch(); // traceId not yet set
// after
if (traceId && spanId) refetch();

if (!traceId || !spanId) return;
const span = await queryClient.fetchQuery({
  queryKey: ['span-detail', traceId, spanId],
  queryFn: () => client.getSpan(traceId, spanId),
});

const isValidSpanSelection = (v: { traceId?: string; spanId?: string }): v is { traceId: string; spanId: string } =>
  Boolean(v.traceId) && Boolean(v.spanId);

try {
  const span = await client.getSpan(traceId, spanId);
} catch (e) {
  if (e instanceof Error && e.message === 'Trace ID and Span ID are required') return null;
  throw e;
}

When it happens

Trigger: Forcing the ['span-detail'] query to run (refetch/fetchQuery) with missing IDs; invoking the hook and manually enabling/refetching before route params resolve; test code calling spanDetail's queryFn without arguments.

Common situations: Span detail panel opened before a span is selected; URL search params not yet hydrated; a refactor renamed the props so undefined IDs are passed through.

Related errors

• traceId and spanId are required
• Trace ID is required
• Trace ID is required
• No Factory selected
• No Factory selected

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