mastra-ai/mastra · critical · MastraError

MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE

MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE

Error message

Observability storage domain is not available

What it means

resolveTraceAndSpan needs the observability storage domain to fetch a trace by id. storage.getStore('observability') returned undefined — meaning no observability store is registered on the Mastra storage backend — so a MastraError (STORAGE/SYSTEM) is thrown. This is a configuration problem, not a data problem.

Source

Thrown at packages/core/src/evals/scoreTraces/scoreTracesWorkflow.ts:177

/** Resolve the target span for a trace/target pair. */
async function resolveTraceAndSpan({
  storage,
  target,
}: {
  storage: MastraStorage;
  target: ScoreTraceTarget;
}): Promise<{ trace: TraceRecord; span: SpanRecord }> {
  if (!isScoreTraceReferenceTarget(target)) {
    return {
      trace: target.trace,
      span: resolveTargetSpan({ trace: target.trace, spanId: target.spanId }),
    };
  }

  // TODO: add storage api to get a single span
  const observabilityStore = await storage.getStore('observability');
  if (!observabilityStore) {
    throw new MastraError({
      id: 'MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE',
      domain: ErrorDomain.STORAGE,
      category: ErrorCategory.SYSTEM,
      text: 'Observability storage domain is not available',
    });
  }
  const trace = await observabilityStore.getTrace({ traceId: target.traceId });
  if (!trace) {
    throw new Error(`Trace not found for scoring, traceId: ${target.traceId}`);
  }

  return { trace, span: resolveTargetSpan({ trace, spanId: target.spanId }) };
}

type TraceScoreResult = Awaited<ReturnType<MastraScorer['run']>>;

/**
 * Run a scorer against an already-resolved trace + span.

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure a storage adapter that supports the observability domain (e.g. @mastra/pg, @mastra/libsql with observability tables).
2. Verify mastra.setStorage()/Mastra({ storage }) is set before running the scoring workflow.
3. Confirm the storage backend's migrations ran so observability tables exist.
4. Ensure the same storage instance that captured the traces is the one scoring uses.
5. Upgrade the storage package if its version lacks getStore('observability').

Example fix

// before
new Mastra({ scorers }) // no storage
// after
import { MastraStorage } from '@mastra/pg';
new Mastra({ scorers, storage: new PostgresStore({ connectionString: process.env.DATABASE_URL }) });

// verify the observability store exists before scoring by trace reference
const store = await storage.getStore('observability');
if (!store) throw new Error('Configure a storage adapter with an observability domain before score-traces');

async function hasObservabilityStore(storage) {
  return (await storage.getStore('observability')) != null;
}

try {
  await scoreTraces({ target: { traceId } });
} catch (e) {
  if (e?.id === 'MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE') {
    throw new Error('Wire Mastra({ storage }) with an adapter supporting observability, e.g. @mastra/pg');
  }
  throw e;
}

When it happens

Trigger: Running the score-traces workflow with a { traceId } reference target while Mastra is configured with a storage adapter that does not provide an observability store (or storage not configured at all), so getStore('observability') yields undefined.

Common situations: Using a minimal/custom MastraStorage implementation without observability tables; storage configured without observability domain enabled; older storage adapter version predating the observability domain; pointing score-traces at a storage instance different from the one that persisted traces.

Related errors

• Trace not found for scoring, traceId: ${target.traceId}
• TokenCostControl requires observability storage with getMetr
• Storage is not available
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}

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