mastra-ai/mastra · critical · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

The stored-skills list handler calls mastra.getStorage() and throws HTTPException 500 'Storage is not configured' when it returns undefined/null. Mastra requires a storage instance for stored skills; without one the server cannot serve the route at all. Unlike the domain-level errors, here no storage object exists whatsoever.

Source

Thrown at packages/server/src/server/handlers/stored-skills.ts:138

  requiresAuth: true,
  handler: async ({
    mastra,
    requestContext,
    page,
    perPage,
    orderBy,
    status,
    authorId,
    visibility,
    metadata,
    favoritedOnly,
    pinFavoritedFor,
  }) => {
    try {
      const storage = mastra.getStorage();

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

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

      const filter = resolveAuthorFilter({
        requestContext,
        resource: 'stored-skills',
        queryAuthorId: authorId,
        queryVisibility: visibility,
      });

      const scope = await getStoredResourceScope(mastra, requestContext);
      const scopedMetadata = scopeStoredResourceMetadata(metadata, scope);

      const callerId = getCallerAuthorId(requestContext);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a storage adapter to the Mastra constructor: new Mastra({ storage: new LibSQLStore({ url: process.env.DATABASE_URL }) })
2. Ensure the storage package (@mastra/libsql, @mastra/pg, etc.) is installed and version-compatible
3. Check server startup logs for storage initialization errors and fix the missing env vars (DATABASE_URL etc.)
4. If intentionally running without persistence, don't expose/enable the builder stored-skills routes

Example fix

// before
new Mastra({ agents }); // no storage

// after
new Mastra({ agents, storage: new LibSQLStore({ url: process.env.DATABASE_URL! }) });

import { mastra } from './mastra';
if (!mastra.getStorage()) {
  throw new Error('Boot aborted: Mastra storage is not configured');
}

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

try {
  return await api.get('/stored/skills');
} catch (e) {
  if (isHttpError(e) && e.status === 500 && e.message === 'Storage is not configured') {
    showStorageSetupGuide(); return emptyPage;
  }
  throw e;
}

When it happens

Trigger: GET (list) /stored/skills (the handler at stored-skills.ts:138) against a Mastra instance constructed without a storage option, or where getStorage() yields undefined due to config resolution failure.

Common situations: Omitting the storage option in new Mastra({...}); storage package not installed or failing to import; environment variable for the storage URL missing so the adapter constructor is skipped; minimal/test server deployments without persistence.

Related errors

• Skills storage domain is not available
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}
• Agents storage domain is not available
• Experiments storage not available

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