mastra-ai/mastra · error · MastraError

OBSERVABILITY_STORAGE_BATCH_CREATE_SPAN_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_BATCH_CREATE_SPAN_NOT_IMPLEMENTED

Error message

This storage provider does not support batch creating spans

What it means

batchCreateSpans() inserts multiple spans in a single write. The ObservabilityStorage base class default throws, so this error means the configured storage adapter has no batch span-write implementation. Note this differs from single-span export: an adapter may support exportSpan but not the batched API.

Source

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

   * 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',
    });
  }

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

View on GitHub (pinned to 75dd419e61)

Solutions

Use a storage adapter that overrides batchCreateSpans (most SQL-backed adapters do).
In your exporter/processor, loop over spans and call the single-span create/export API per span.
Implement batchCreateSpans() in your custom adapter (bulk INSERT).
If persistence isn't required, export spans to an OTLP/telemetry endpoint instead of Mastra storage.

Example fix

// before
await observability.batchCreateSpans({ spans: buffer });

// after (fallback)
for (const span of buffer) {
  await observability.exportSpan(span);
}

Defensive patterns

Strategy: fallback

Validate before calling

const supportsBatchCreate = obs.batchCreateSpans !== ObservabilityStorage.prototype.batchCreateSpans;

Type guard

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

Try / catch

try {
  await obs.batchCreateSpans({ spans: buffer });
} catch (e) {
  if ((e as MastraError).id === 'OBSERVABILITY_STORAGE_BATCH_CREATE_SPAN_NOT_IMPLEMENTED') {
    await Promise.all(buffer.map(s => obs.exportSpan(s)));
  } else throw e;
}

Prevention

Detect batch support in the exporter and choose bulk vs per-span writes once at startup.
Implement batchCreateSpans with a bulk INSERT in custom adapters for performance.
Cover the batch-write path in adapter integration tests.

When it happens

Trigger: Calling storage.getObservability().batchCreateSpans({ spans }) — e.g. a flushing observability exporter that buffers spans and writes them in bulk — against an adapter that kept the base default.

Common situations: Observability exporters configured with batching enabled pointing at a storage backend without bulk inserts; custom adapters that only implement per-span export; high-throughput setups that assume batch writes for performance.

Related errors

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