mastra-ai/mastra · error · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

The agent-versions list handler requires a configured storage layer: `mastra.getStorage()` returning undefined triggers HTTP 500 'Storage is not configured'. Agent versions are persisted, so version history endpoints cannot function without storage.

Source

Thrown at packages/server/src/server/handlers/agent-versions.ts:78

 * GET /stored/agents/:agentId/versions - List all versions for an agent
 */
export const LIST_AGENT_VERSIONS_ROUTE = createRoute({
  method: 'GET',
  path: '/stored/agents/:agentId/versions',
  requiresAuth: true,
  responseType: 'json',
  pathParamSchema: agentVersionPathParams,
  queryParamSchema: listVersionsQuerySchema,
  responseSchema: listVersionsResponseSchema,
  summary: 'List agent versions',
  description: 'Returns a paginated list of all versions for a stored agent',
  tags: ['Agent Versions'],
  handler: async ({ mastra, agentId, page, perPage, orderBy, requestContext }) => {
    try {
      const storage = mastra.getStorage();

      if (!storage) {
        throw new HTTPException(500, { message: 'Storage is not configured' });
      }

      const agentsStore = await storage.getStore('agents');
      if (!agentsStore) {
        throw new HTTPException(500, { message: 'Agents storage domain is not available' });
      }

      // Verify agent exists in code or storage
      const storedAgent = await agentsStore.getById(agentId);
      let codeAgentExists = false;
      try {
        mastra.getAgentById(agentId);
        codeAgentExists = true;
      } catch {
        // Agent not registered in code
      }

      if (!storedAgent && !codeAgentExists) {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure storage on your Mastra instance, e.g. `new Mastra({ storage: new LibSQLStore({ url: 'file:./mastra.db' }) })` (or PostgresStore etc.).
2. Verify the storage dependency/adapter is installed and the env vars (connection URL) are set.
3. Confirm the server loads the same Mastra config that includes storage (check mastra.config/entrypoint).
4. If storage is intentionally absent, avoid agent-version endpoints or feature-flag them in the client.

Example fix

// before
export const mastra = new Mastra({ agents: {} });
// after
import { LibSQLStore } from '@mastra/libsql';
export const mastra = new Mastra({ agents: {}, storage: new LibSQLStore({ url: process.env.DB_URL ?? 'file:./mastra.db' }) });

import { Mastra } from '@mastra/core';
const mastra = getMastra();
if (!mastra.getStorage()) {
  throw new Error('Storage must be configured to use agent-version endpoints: new Mastra({ storage: ... })');
}

function hasStorage(m: { getStorage(): unknown }): boolean {
  return m.getStorage() != null;
}

try {
  return await api.listAgentVersions({ agentId });
} catch (e) {
  if (isHttpError(e) && e.status === 500 && e.message.includes('Storage is not configured')) {
    throw new Error('Enable persistence: configure a storage adapter on the Mastra instance');
  }
  throw e;
}

When it happens

Trigger: Calling agent-version endpoints on a Mastra instance constructed without storage (no `storage:` option / no storage configured in mastra config), or in ephemeral setups where storage was intentionally omitted.

Common situations: Fresh projects following quickstart configs without persistence; tests/dev running with in-memory defaults and no storage; misconfigured env vars so the storage constructor is skipped; deploying without adding a storage adapter (LibSQL/Postgres/upstash).

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Storage is not configured
• Storage not configured
• Storage is not configured

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