mastra-ai/mastra · error · MastraError

OBSERVABILITY_STORAGE_BATCH_UPDATE_SPANS_NOT_IMPLEMENTED

OBSERVABILITY_STORAGE_BATCH_UPDATE_SPANS_NOT_IMPLEMENTED

Error message

This storage provider does not support batch updating spans

What it means

This error is thrown by the base MastraObservabilityStorage class's batchUpdateSpans method, which is a default implementation that always throws. It means the concrete storage provider in use has not overridden batchUpdateSpans, so it does not support updating multiple spans in a single batch operation. The library throws it to signal an unimplemented optional capability rather than silently failing or corrupting trace data.

Source

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

  }

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

  /**
   * Deletes multiple traces and all their associated spans in a single batch operation.
   */
  async batchDeleteTraces(_args: BatchDeleteTracesArgs): Promise<void> {
    throw new MastraError({
      id: 'OBSERVABILITY_STORAGE_BATCH_DELETE_TRACES_NOT_IMPLEMENTED',
      domain: ErrorDomain.MASTRA_OBSERVABILITY,
      category: ErrorCategory.SYSTEM,
      text: 'This storage provider does not support batch deleting traces',
    });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

Check whether your storage provider supports batch span updates; if it does, verify you are instantiating that provider class (not the base class).
Switch to a storage provider that implements batchUpdateSpans (e.g. a database-backed provider like Postgres/LibSQL with full observability support).
Update spans one at a time via the single-span update API if your provider exposes it.
If you own the provider, override batchUpdateSpans to persist all spans in one transaction.
If batching is optional in your integration, catch this error and fall back to per-span updates.

Example fix

// before
await storage.batchUpdateSpans({ spans });
// after
try {
  await storage.batchUpdateSpans({ spans });
} catch (e) {
  if (e instanceof MastraError && e.id === 'OBSERVABILITY_STORAGE_BATCH_UPDATE_SPANS_NOT_IMPLEMENTED') {
    for (const span of spans) await storage.updateSpan(span);
  } else {
    throw e;
  }
}

Defensive patterns

Strategy: try-catch

Validate before calling

const supportsBatchSpanUpdates = typeof storage.batchUpdateSpans === 'function' && !Object.getPrototypeOf(storage).constructor.name.includes('Base') && storage.batchUpdateSpans !== MastraObservabilityStorage.prototype.batchUpdateSpans;
if (!supportsBatchSpanUpdates) { /* use per-span update path */ }

Type guard

function supportsBatchUpdateSpans(s: unknown): s is MastraObservabilityStorage & { batchUpdateSpans: (a: BatchUpdateSpansArgs) => Promise<void> } {
  return s instanceof MastraObservabilityStorage && (s as any).batchUpdateSpans !== MastraObservabilityStorage.prototype.batchUpdateSpans;
}

Try / catch

try {
  await storage.batchUpdateSpans({ spans });
} catch (e) {
  if (e instanceof MastraError && e.id === 'OBSERVABILITY_STORAGE_BATCH_UPDATE_SPANS_NOT_IMPLEMENTED') {
    await Promise.all(spans.map(s => storage.updateSpan(s)));
  } else {
    throw e;
  }
}

Prevention

Check the provider's documentation/implemented methods before relying on batch observability APIs.
Verify which concrete storage class you instantiate — never use the base class directly.
Feature-detect batch methods (compare against the base prototype) before calling them.
When writing custom providers, implement all batch methods you intend callers to use.
Add an integration test asserting batch behavior for every storage provider you ship.

When it happens

Trigger: Calling storage.batchUpdateSpans(args) (BatchUpdateSpansArgs) on a storage provider class that does not override batchUpdateSpans, e.g. a custom provider extending only the base class, or an official provider that has not implemented batch span updates.

Common situations: Using a lightweight or in-memory storage adapter that only implements the required observability methods; writing a custom storage driver that extends the base class without implementing batch methods; enabling a tracing/observability exporter that assumes batch span updates are available; upgrading Mastra and enabling a new batch-based span pipeline against an older provider.

Related errors

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