mastra-ai/mastra · error · MastraError

OBSERVABILITY_STORAGE_GET_STRUCTURE_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_GET_STRUCTURE_NOT_IMPLEMENTED

Error message

This storage provider does not support getting trace structure

What it means

getStructure() returns a lightweight tree/structure view of a trace. Its default base implementation only throws when the adapter also left getTraceLight() at the default: the two methods delegate to each other, so if neither is overridden the base class throws this error to signal the backend supports no structure surface at all.

Source

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

      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.
   */
  async getStructure(args: GetTraceArgs): Promise<GetStructureResponse | null> {
    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',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Override getStructure() (preferred, canonical name) in your storage adapter; getTraceLight will then forward to it automatically.
2. If full structure isn't needed, fall back to getTrace() and build the tree client-side from parentId links.
3. Upgrade the storage package to a version whose adapters implement getStructure.
4. Feature-detect with `adapter.getStructure !== ObservabilityStorage.prototype.getStructure` before calling.

Example fix

// before
class MyStore extends ObservabilityStorage { /* only getTrace overridden */ }

// after
class MyStore extends ObservabilityStorage {
  async getStructure(args) {
    const trace = await this.getTrace(args);
    return trace ? toStructure(trace) : null;
  }
}

const supportsStructure = obs.getStructure !== ObservabilityStorage.prototype.getStructure;
if (!supportsStructure) throw new Error('Storage adapter does not implement getStructure');

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

try {
  return await obs.getStructure({ traceId });
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_GET_STRUCTURE_NOT_IMPLEMENTED') {
    const trace = await obs.getTrace({ traceId }).catch(() => null);
    return trace ? toStructure(trace) : null;
  }
  throw e;
}

When it happens

Trigger: Calling getStructure({ traceId }) (or getTraceLight()/skeleton paths that delegate to it) on an adapter where BOTH getStructure and getTraceLight remain the ObservabilityStorage prototype defaults.

Common situations: Custom storage adapters that implement only full-trace reads (getTrace) and not the optimized structure endpoints; adapter versions from before the getStructure/getTraceLight pair was introduced; UI skeleton loading that assumes structure support.

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_TRACE_LIGHT_NOT_IMPLEMENTED

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