{"record":{"id":"ffe4bac4eea59cbe","repo":"mastra-ai/mastra","slug":"storage-is-not-available","errorCode":null,"errorMessage":"Storage is not available","messagePattern":"Storage is not available","errorType":"http","errorClass":"HTTPException","httpStatus":500,"severity":"error","filePath":"packages/server/src/server/handlers/observability-shared.ts","lineNumber":43,"sourceCode":"  feedback: 'feedback',\n} as const;\n\nexport type ObservabilityListEndpoint =\n  (typeof OBSERVABILITY_LIST_ENDPOINTS)[keyof typeof OBSERVABILITY_LIST_ENDPOINTS];\nconst OBSERVABILITY_DELTA_POLLING_STORAGE_FEATURE = 'delta-polling';\n\nfunction getFeatures(observabilityStore: ObservabilityStorage): readonly string[] | undefined {\n  const candidate = observabilityStore as ObservabilityStorage & {\n    getFeatures?: () => readonly string[] | undefined;\n  };\n  return candidate.getFeatures?.();\n}\n\n/** Retrieves MastraCompositeStore or throws 500 if unavailable. */\nexport function getStorage(mastra: Mastra): MastraCompositeStore {\n  const storage = mastra.getStorage();\n  if (!storage) {\n    throw new HTTPException(500, { message: 'Storage is not available' });\n  }\n  return storage;\n}\n\n/** Retrieves the observability storage domain or throws 501 if unavailable. */\nexport async function getObservabilityStore(mastra: Mastra): Promise<ObservabilityStorage> {\n  const storage = getStorage(mastra);\n  const observability = await storage.getStore('observability');\n  if (!observability) {\n    // 501, not 500: a missing or explicitly disabled observability domain\n    // (e.g. `domains: { observability: false }`) is a capability gap, not a\n    // server failure — matching the other 501s in this file.\n    throw new HTTPException(501, { message: 'Observability storage domain is not available' });\n  }\n  return observability;\n}\n\n/** Retrieves the scores storage domain or throws 501 if unavailable. */","sourceCodeStart":25,"sourceCodeEnd":61,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/observability-shared.ts#L25-L61","documentation":"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.","triggerScenarios":"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().","commonSituations":"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).","solutions":["Configure storage on the Mastra instance: new Mastra({ storage: new LibSQLStore({ url: ... }) }) (or PgStore/UpstashStore).","If storage should already exist, check that mastra.getStorage() isn't returning undefined due to failed/env-missing initialization of the adapter.","For observability specifically, also ensure getObservabilityStore's domain is supported by your adapter (this 500 precedes the 501 domain check).","In route handlers, validate storage presence before calling observability endpoints and surface a config error instead of a 500."],"exampleFix":"// before\nexport const mastra = new Mastra({ agents, observability: { default: { enabled: true } } });\n// after\nexport const mastra = new Mastra({\n  agents,\n  storage: new LibSQLStore({ url: process.env.DB_URL }),\n  observability: { default: { enabled: true } },\n});","handlingStrategy":"type-guard","validationCode":"if (!mastra.getStorage()) {\n  throw new Error('Observability requires storage; add a storage adapter to the Mastra constructor.');\n}","typeGuard":"function hasStorage(mastra: Mastra): mastra is Mastra & { getStorage: () => NonNullable<ReturnType<Mastra['getStorage']>> } {\n  return !!mastra.getStorage();\n}","tryCatchPattern":"try {\n  const storage = getStorage(mastra);\n} catch (e) {\n  if (e instanceof HTTPException && e.status === 500 && e.message === 'Storage is not available') {\n    console.error('Configure storage on Mastra before using observability features.');\n  } else throw e;\n}","preventionTips":["Always configure storage when enabling observability/tracing.","Fail fast at boot: assert mastra.getStorage() is defined in your entrypoint.","Check env vars (DB_URL etc.) used by the storage adapter constructor."],"tags":["storage","observability","http-500","configuration"],"backgroundTag":"storage-not-available","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}