mastra-ai/mastra · error · MastraError

OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED

Error message

This storage provider does not support listing trace branches

What it means

listBranches() returns one row per branch anchor span (each runnable branch of a trace, not just one per root), designed to pair with getBranch() to expand a branch into its subtree. The base class default throws, meaning the adapter does not support branch-level trace listing.

Source

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

   * serves the same response shape whether or not it has a dedicated implementation.
   * Backends that can push the projection into the query should override this --
   * that is what actually keeps the blob columns off the read path -- but the
   * fallback stays correct, just not cheaper than `listTraces`.
   */
  async listTracesLight(args: ListTracesArgs): Promise<ListTracesLightResponse> {
    const { spans, ...rest } = await this.listTraces(args);
    return { ...rest, spans: spans.map(toLightSpanRecord) };
  }

  /**
   * Lists trace branches across all traces. Unlike {@link listTraces} (which
   * returns one row per root-rooted trace), each row here is a single branch
   * anchor span, including ones nested under a different root entity -- useful
   * for "show me every run of agent X" regardless of caller. Pairs with
   * {@link getBranch} to expand a single branch into its subtree.
   */
  async listBranches(_args: ListBranchesArgs): Promise<ListBranchesResponse> {
    throw new MastraError({
      id: 'OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED',
      domain: ErrorDomain.MASTRA_OBSERVABILITY,
      category: ErrorCategory.SYSTEM,
      text: 'This storage provider does not support listing trace branches',
    });
  }

  /**
   * Creates multiple Spans in a single batch.
   */
  async batchCreateSpans(_args: BatchCreateSpansArgs): Promise<void> {
    throw new MastraError({
      id: 'OBSERVABILITY_STORAGE_BATCH_CREATE_SPAN_NOT_IMPLEMENTED',
      domain: ErrorDomain.MASTRA_OBSERVABILITY,
      category: ErrorCategory.SYSTEM,
      text: 'This storage provider does not support batch creating spans',
    });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Use a storage adapter that implements listBranches (upgrade the storage package if needed).
2. Implement listBranches() in your adapter (select anchor spans and derive branch metadata).
3. Fall back to listTraces()/getTrace() and enumerate branches by walking parent-child links client-side.
4. Capability-check before calling and degrade to root-level trace listing.

Example fix

// before
const branches = await observability.listBranches(args);

// after (fallback)
const { traces } = await observability.listTraces(args);
const branches = traces; // root-level listing as coarse approximation

const supportsListBranches = obs.listBranches !== ObservabilityStorage.prototype.listBranches;

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

try {
  return await obs.listBranches(args);
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_LIST_BRANCHES_NOT_IMPLEMENTED') {
    const { traces } = await obs.listTraces(args).catch(() => ({ traces: [] }));
    return traces;
  }
  throw e;
}

When it happens

Trigger: Calling listBranches({ ... }) — e.g. 'show me every run of agent X' style queries — on an adapter that never overrode it; UI routes enumerating branches before calling getBranch().

Common situations: Adapters implementing flat trace listing (listTraces) but not the newer branch model; custom storage written before branch-aware observability; minimal backends without nested-run 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_STRUCTURE_NOT_IMPLEMENTED

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