mastra-ai/mastra · critical · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

getFavoritesContext resolves storage via mastra.getStorage() for the stored-agent favorites endpoints. If no storage is configured on the Mastra instance, it throws HTTPException 500 because favorites cannot be persisted without a storage backend. The library requires an explicit storage configuration for builder favorites features.

Source

Thrown at packages/server/src/server/handlers/stored-agent-favorites.ts:17

import { HTTPException } from '../http-exception';
import { favoriteToggleResponseSchema } from '../schemas/favorites';
import { storedAgentIdPathParams } from '../schemas/stored-agents';
import { createRoute } from '../server-adapter/routes/route-builder';
import { assertStoredResourceScope, getStoredResourceScope } from '../utils';

import { assertReadAccess, getCallerAuthorId } from './authorship';
import { requireBuilderFeature } from './editor-builder';
import { handleError } from './error';

/**
 * Resolves the storage and favorites domains, throwing 500 if unavailable.
 */
async function getFavoritesContext(mastra: Parameters<typeof requireBuilderFeature>[0]) {
  const storage = mastra.getStorage();
  if (!storage) {
    throw new HTTPException(500, { message: 'Storage is not configured' });
  }
  const agentStore = await storage.getStore('agents');
  if (!agentStore) {
    throw new HTTPException(500, { message: 'Agents storage domain is not available' });
  }
  const favoritesStore = await storage.getStore('favorites');
  if (!favoritesStore) {
    throw new HTTPException(500, { message: 'Favorites storage domain is not available' });
  }
  return { agentStore, favoritesStore };
}

/**
 * PUT /stored/agents/:storedAgentId/favorite
 */
export const FAVORITE_STORED_AGENT_ROUTE = createRoute({
  method: 'PUT',
  path: '/stored/agents/:storedAgentId/favorite',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Configure storage when creating the Mastra instance: new Mastra({ storage: new MastraStorage(...) })
2. Verify the storage config file/env is actually loaded in the deployment
3. Use a real storage adapter (e.g. LibSQL, Postgres) instead of relying on defaults
4. If favorites aren't needed, disable the builder favorites feature rather than leaving endpoints half-configured

Example fix

// before
new Mastra({ agents })
// after
new Mastra({ agents, storage: new MastraLibSQLStorage({ url: process.env.DATABASE_URL }) })

// At server startup
const storage = mastra.getStorage();
if (!storage) throw new Error('Mastra server requires storage configuration for favorites features');

function hasStorage(mastra: Mastra): boolean {
  return mastra.getStorage() != null;
}

try {
  await client.toggleFavorite(agentId);
} catch (e) {
  if (e.status === 500 && /Storage is not configured/.test(e.message)) {
    notifyAdmin('Favorites unavailable: server storage missing');
  } else throw e;
}

When it happens

Trigger: Calling any /stored/agents/:id/favorite endpoint (PUT toggle, GET list) on a Mastra server instance constructed without a storage option.

Common situations: Server bootstrapped with in-memory/no storage in development; storage config removed or never added; environment-specific config file not loading; using requireBuilderFeature('favorites') with favorites enabled but storage omitted.

Related errors

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

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