mastra-ai/mastra · error · MastraError

OBSERVABILITY_STORAGE_GET_TRACE_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_GET_TRACE_NOT_IMPLEMENTED

Error message

This storage provider does not support getting traces

What it means

getTrace() on the ObservabilityStorage base class throws unless the adapter overrides it. It fetches one trace with all its spans; throwing means the configured storage backend has no trace-read capability. Called internally by the trace accessor path.

Source

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

  }

  /**
   * Retrieves a single root span.
   */
  async getRootSpan(_args: GetRootSpanArgs): Promise<GetRootSpanResponse | null> {
    throw new MastraError({
      id: 'OBSERVABILITY_STORAGE_GET_ROOT_SPAN_NOT_IMPLEMENTED',
      domain: ErrorDomain.MASTRA_OBSERVABILITY,
      category: ErrorCategory.SYSTEM,
      text: 'This storage provider does not support getting root spans',
    });
  }

  /**
   * Retrieves a single trace with all its associated spans.
   */
  async getTrace(_args: GetTraceArgs): Promise<GetTraceResponse | null> {
    throw new MastraError({
      id: 'OBSERVABILITY_STORAGE_GET_TRACE_NOT_IMPLEMENTED',
      domain: ErrorDomain.MASTRA_OBSERVABILITY,
      category: ErrorCategory.SYSTEM,
      text: 'This storage provider does not support getting traces',
    });
  }

  /**
   * Retrieves the structural skeleton of a trace -- parent/child links, span
   * type, timing, and status -- with heavy fields (input, output, attributes,
   * metadata, tags, links) excluded. Intended for waterfall/timeline rendering
   * where the full payload would be wasteful.
   *
   * Default implementation forwards to {@link getTraceLight} (the legacy
   * override surface). Backends should override either method -- the response
   * shape is identical, and the unimplemented one delegates to the
   * implemented one. The cycle guard is what makes that safe.
   */

View on GitHub (pinned to 75dd419e61)

Solutions

Switch to a storage backend that implements trace reads (libsql/pg/upstash/adapters that override getTrace).
If you maintain a custom adapter, implement getTrace() by fetching all spans WHERE traceId = ? and grouping them.
If only a span listing is needed and the backend implements it, use getSpans() or listTraces() instead.
Add a capability check before calling and return a clear 'traces unavailable' state in your app.

Defensive patterns

Strategy: try-catch

Validate before calling

const supportsGetTrace = obs.getTrace !== ObservabilityStorage.prototype.getTrace;

Type guard

function supportsGetTrace(o: { getTrace: unknown }): o is { getTrace: (a: any) => Promise<any> } {
  return o.getTrace !== (ObservabilityStorage.prototype as any).getTrace;
}

Try / catch

try {
  return await obs.getTrace({ traceId });
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_GET_TRACE_NOT_IMPLEMENTED') {
    return null;
  }
  throw e;
}

Prevention

Choose adapters documented as supporting trace reads when you need trace inspection.
Run a smoke query (getTrace on a known trace) in your storage bootstrap.
Pin adapter versions that include observability read methods.

When it happens

Trigger: Calling storage.getObservability().getTrace({ traceId }) (directly or through the trace() helper / traces UI) against an adapter that kept the base-class default.

Common situations: Minimal in-memory or custom storage used in tests that only supports span export; adapters that implement AI/agent domains but not observability reads; version drift where an older adapter build predates getTrace.

Related errors

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