mastra-ai/mastra · warning · MastraError

OBSERVABILITY_STORAGE_GET_TRACE_LIGHT_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_GET_TRACE_LIGHT_NOT_IMPLEMENTED

Error message

This storage provider does not support getting lightweight traces

What it means

getTraceLight() is the deprecated legacy name for the lightweight trace view; its default forwards to getStructure(). The base class throws this error only when the adapter also left getStructure() at the default — i.e. the backend implements neither lightweight-trace method. Migrate to getStructure().

Source

Thrown at packages/core/src/storage/domains/observability/base.ts:252

    if (this.getTraceLight === ObservabilityStorage.prototype.getTraceLight) {
      throw new MastraError({
        id: 'OBSERVABILITY_STORAGE_GET_STRUCTURE_NOT_IMPLEMENTED',
        domain: ErrorDomain.MASTRA_OBSERVABILITY,
        category: ErrorCategory.SYSTEM,
        text: 'This storage provider does not support getting trace structure',
      });
    }
    return this.getTraceLight(args);
  }

  /**
   * @deprecated Use {@link getStructure} instead. Default implementation
   * forwards to {@link getStructure} so backends that only override the
   * canonical name still work for legacy callers.
   */
  async getTraceLight(args: GetTraceArgs): Promise<GetTraceLightResponse | null> {
    if (this.getStructure === ObservabilityStorage.prototype.getStructure) {
      throw new MastraError({
        id: 'OBSERVABILITY_STORAGE_GET_TRACE_LIGHT_NOT_IMPLEMENTED',
        domain: ErrorDomain.MASTRA_OBSERVABILITY,
        category: ErrorCategory.SYSTEM,
        text: 'This storage provider does not support getting lightweight traces',
      });
    }
    return this.getStructure(args);
  }

  /**
   * Retrieves the subtree of spans rooted at a given span, optionally bounded
   * to `depth` levels of descendants.
   *
   * Default implementation prefers a two-step path: fetch the lightweight
   * structure to determine which spans belong to the branch, then batch-fetch
   * only those with full data. This avoids pulling the entire trace when the
   * branch is a small slice of a large trace. Backends that don't yet
   * implement {@link getStructure} or {@link getSpans} fall back to fetching

View on GitHub (pinned to 75dd419e61)

Solutions

1. Replace getTraceLight() calls with getStructure() — the response shape is identical and it is the canonical method.
2. Use a storage adapter that overrides getStructure (then getTraceLight forwards automatically).
3. Override getStructure() in your custom adapter.
4. Fall back to getTrace() and derive the lightweight view client-side.

Example fix

// before
const light = await observability.getTraceLight({ traceId });

// after
const structure = await observability.getStructure({ traceId });

const supportsTraceLight = obs.getTraceLight !== ObservabilityStorage.prototype.getTraceLight;

function supportsGetTraceLight(o: { getTraceLight: unknown }): boolean {
  return o.getTraceLight !== (ObservabilityStorage.prototype as any).getTraceLight;
}

try {
  return await obs.getTraceLight(args);
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_GET_TRACE_LIGHT_NOT_IMPLEMENTED') {
    return obs.getStructure(args).catch(() => null);
  }
  throw e;
}

When it happens

Trigger: Calling getTraceLight({ traceId }) (legacy callers) on an adapter where BOTH getTraceLight and getStructure are the prototype defaults; any legacy UI/server route still using the deprecated name against an adapter without structure support.

Common situations: Old code paths written against getTraceLight before it was deprecated; third-party storage adapters that never implemented the lightweight endpoints; upgrading Mastra where callers must switch to getStructure.

Related errors

• OBSERVABILITY_STORAGE_UPDATE_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_ROOT_SPAN_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_TRACE_NOT_IMPLEMENTED
• OBSERVABILITY_STORAGE_GET_STRUCTURE_NOT_IMPLEMENTED

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