mastra-ai/mastra · error · HTTPException

Storage is not available

Error message

Storage is not available

What it means

getStorage in observability-shared.ts calls mastra.getStorage() and throws HTTPException(500, 'Storage is not available') when the Mastra instance has no storage configured. All observability features that depend on storage (traces, scores, workflow observability, schedules) rely on this, so it fires for any observability request served by a Mastra instance built without storage.

Source

Thrown at packages/server/src/server/handlers/observability-shared.ts:43

  feedback: 'feedback',
} as const;

export type ObservabilityListEndpoint =
  (typeof OBSERVABILITY_LIST_ENDPOINTS)[keyof typeof OBSERVABILITY_LIST_ENDPOINTS];
const OBSERVABILITY_DELTA_POLLING_STORAGE_FEATURE = 'delta-polling';

function getFeatures(observabilityStore: ObservabilityStorage): readonly string[] | undefined {
  const candidate = observabilityStore as ObservabilityStorage & {
    getFeatures?: () => readonly string[] | undefined;
  };
  return candidate.getFeatures?.();
}

/** Retrieves MastraCompositeStore or throws 500 if unavailable. */
export function getStorage(mastra: Mastra): MastraCompositeStore {
  const storage = mastra.getStorage();
  if (!storage) {
    throw new HTTPException(500, { message: 'Storage is not available' });
  }
  return storage;
}

/** Retrieves the observability storage domain or throws 501 if unavailable. */
export async function getObservabilityStore(mastra: Mastra): Promise<ObservabilityStorage> {
  const storage = getStorage(mastra);
  const observability = await storage.getStore('observability');
  if (!observability) {
    // 501, not 500: a missing or explicitly disabled observability domain
    // (e.g. `domains: { observability: false }`) is a capability gap, not a
    // server failure — matching the other 501s in this file.
    throw new HTTPException(501, { message: 'Observability storage domain is not available' });
  }
  return observability;
}

/** Retrieves the scores storage domain or throws 501 if unavailable. */

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure storage on the Mastra instance: new Mastra({ storage: new LibSQLStore({ url: ... }) }) (or PgStore/UpstashStore).
2. If storage should already exist, check that mastra.getStorage() isn't returning undefined due to failed/env-missing initialization of the adapter.
3. For observability specifically, also ensure getObservabilityStore's domain is supported by your adapter (this 500 precedes the 501 domain check).
4. In route handlers, validate storage presence before calling observability endpoints and surface a config error instead of a 500.

Example fix

// before
export const mastra = new Mastra({ agents, observability: { default: { enabled: true } } });
// after
export const mastra = new Mastra({
  agents,
  storage: new LibSQLStore({ url: process.env.DB_URL }),
  observability: { default: { enabled: true } },
});

if (!mastra.getStorage()) {
  throw new Error('Observability requires storage; add a storage adapter to the Mastra constructor.');
}

function hasStorage(mastra: Mastra): mastra is Mastra & { getStorage: () => NonNullable<ReturnType<Mastra['getStorage']>> } {
  return !!mastra.getStorage();
}

try {
  const storage = getStorage(mastra);
} catch (e) {
  if (e instanceof HTTPException && e.status === 500 && e.message === 'Storage is not available') {
    console.error('Configure storage on Mastra before using observability features.');
  } else throw e;
}

When it happens

Trigger: Any observability route or helper calling getStorage/getStorageFromContext/workflowsStore/scores on a Mastra constructed without `storage`, or with a storage adapter that returns undefined from getStorage().

Common situations: Mastra({ agents }) without storage in a server deployment; observability/tracing enabled but no storage adapter added; tests instantiating Mastra minimally then exercising observability routes; storage configured via env-based constructor that silently failed (bad DB_URL swallowed).

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• MASTRA_OBSERVABILITY_STORAGE_NOT_AVAILABLE
• TokenCostControl requires observability storage with getMetr
• Storage is not configured

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