What causes "Storage not configured" in mastra-ai/mastra?

Configure storage on the Mastra instance: `new Mastra({ storage: new MastraLibsqlStorage({ url: 'file:./mastra.db' }) })` or your preferred adapter.

mastra-ai/mastra · error · HTTPException

Storage not configured

Error message

Storage not configured

What it means

Thrown by the score-saving handler when `mastra.getStorage()` returns undefined or the scores store/saveScore is unavailable, so no result is produced. The server requires a configured storage backend to persist scoring data; without one, saving a score cannot succeed.

Source

Thrown at packages/server/src/server/handlers/scores.ts:349

});

export const SAVE_SCORE_ROUTE = createRoute({
  method: 'POST',
  path: '/scores',
  responseType: 'json',
  bodySchema: saveScoreBodySchema,
  responseSchema: saveScoreResponseSchema,
  summary: 'Save score',
  description: 'Saves a new score record to storage',
  tags: ['Scoring'],
  requiresAuth: true,
  handler: async ({ mastra, ...params }) => {
    try {
      const { score } = params as { score: ScoreRowData };
      const scoresStore = await mastra.getStorage()?.getStore('scores');
      const result = await scoresStore?.saveScore?.(score);
      if (!result) {
        throw new HTTPException(500, { message: 'Storage not configured' });
      }
      return result;
    } catch (error) {
      return handleError(error, 'Error saving score');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

Configure storage on the Mastra instance: `new Mastra({ storage: new MastraLibsqlStorage({ url: 'file:./mastra.db' }) })` or your preferred adapter.
Verify the storage adapter implements the scores store (`getStore('scores')` and `saveScore`).
Upgrade @mastra/core and your storage package to compatible versions.
Check that storage-related env vars (DB URL, connection string) are set in the server environment.

Example fix

// before
export const mastra = new Mastra({ agents: { weatherAgent } });
// after
import { MastraStorage } from '@mastra/core/storage';
export const mastra = new Mastra({ agents: { weatherAgent }, storage: new LibSQLStore({ url: process.env.DATABASE_URL }) });

Defensive patterns

Strategy: validation

Validate before calling

const storage = mastra.getStorage();
if (!storage) throw new Error('Mastra storage is not configured; scores cannot be saved.');
const scoresStore = await storage.getStore('scores');
if (!scoresStore?.saveScore) throw new Error('Configured storage does not support the scores store.');

Type guard

function hasScoresStore(s): s is { getStore: (n: 'scores') => Promise<{ saveScore: Function } | undefined> | undefined } {
  return typeof s?.getStore === 'function';
}

Try / catch

try {
  await client.saveScore(score);
} catch (e) {
  if (e instanceof MastraClientError && e.status === 500 && /Storage not configured/.test(e.message)) {
    console.error('Server has no storage backend; configure `storage` on the Mastra instance.');
  } else throw e;
}

Prevention

Always pass a `storage` adapter when constructing the Mastra instance served by the server.
Smoke-test storage at startup (e.g. write and read a trivial record) before accepting traffic.
Keep @mastra/core and the storage package versions aligned so the scores store exists.
Set and verify storage env vars in every deployment environment.

When it happens

Trigger: POSTing to the scores endpoint on a Mastra instance constructed without a `storage` option, or with a storage backend that lacks a scores store (e.g. a storage adapter that does not implement saveScore).

Common situations: Forgetting to pass storage in `new Mastra({...})`; using an in-memory/dev setup in production; a storage package version that predates the scores store API; storage misconfigured env vars preventing initialization.

Related errors

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