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

Configure storage on the Mastra instance (e.g. new Mastra({ storage: new MastraLibsqlStorage({...}) }) or your preferred adapter) and restart the server.

mastra-ai/mastra · error · HTTPException

Storage is not configured

Error message

Storage is not configured

What it means

The builder-registry install-skill handler requires persistent storage to save the imported skill. It throws a 500 HTTPException when mastra.getStorage() returns null/undefined, meaning no storage was configured on the Mastra instance. Without storage, imported registry skills cannot be persisted, so the operation fails fast.

Source

Thrown at packages/server/src/server/handlers/builder-registry.ts:336

export const BUILDER_REGISTRY_INSTALL_ROUTE = createRoute({
  method: 'POST',
  path: '/editor/builder/registries/:registryId/install',
  responseType: 'json',
  pathParamSchema: builderRegistryPathParams,
  bodySchema: builderRegistryInstallBodySchema,
  responseSchema: builderRegistryInstallResponseSchema,
  summary: 'Install a registry skill into stored skills',
  description: 'Fetches a skill from the configured registry and persists it as a new stored skill.',
  tags: ['Editor', 'Skills'],
  requiresAuth: true,
  requiresPermission: 'stored-skills:write',
  handler: async ({ mastra, requestContext, registryId, owner, repo, skillName, visibility: bodyVisibility }) => {
    try {
      await requireEnabledRegistry(mastra, registryId);

      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' });
      }

      // Pull files from the registry
      const result = await fetchSkillFiles(owner, repo, skillName);
      if (!result || result.files.length === 0) {
        throw new HTTPException(404, {
          message: `Could not find skill "${skillName}" in ${owner}/${repo}.`,
        });
      }

      const safeSkillId = assertSafeSkillName(result.skillId);
      const files = buildFileTree(result.files);

      // Parse SKILL.md frontmatter into structured fields. Splitting

View on GitHub (pinned to 75dd419e61)

Solutions

Configure storage on the Mastra instance (e.g. new Mastra({ storage: new MastraLibsqlStorage({...}) }) or your preferred adapter) and restart the server.
Verify with a quick runtime check that mastra.getStorage() returns an object in your deployment.
If storage is intentionally absent, do not use the builder-registry install route; import skills directly into whatever persistence you use.
Confirm the storage package is installed and its constructor does not silently fail.

Example fix

// before
new Mastra({ agents, logger });

// after
import { MastraStorageLibSQL } from '@mastra/storage-libsql';
new Mastra({ agents, logger, storage: new MastraStorageLibSQL({ url: process.env.DATABASE_URL }) });

Defensive patterns

Strategy: validation

Validate before calling

// server-side guard before enabling builder-registry routes
if (!mastra.getStorage()) {
  throw new Error('builder-registry install requires storage; configure Mastra storage');
}

Type guard

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

Try / catch

try {
  await installSkill(payload);
} catch (e) {
  if (e.status === 500 && e.message === 'Storage is not configured') {
    // surface a config error to the operator, not the end user
  } else throw e;
}

Prevention

Always configure storage in production Mastra instances.
Add a startup assertion that getStorage() returns a value when builder features are enabled.
Keep storage configuration in shared config so dev/prod parity holds.
Document that builder-registry install is a persistence-requiring feature.

When it happens

Trigger: POSTing to the builder-registry install route (with a valid, enabled registryId, owner, repo, skillName) on a Mastra instance that was constructed without a storage configuration.

Common situations: Local/dev Mastra instances with no storage configured; storage removed during a config refactor; in-memory instance deployed where persistence is now required for builder features; wrong Mastra instance (one without storage) serving the playground.

Related errors

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