mastra-ai/mastra · error · HTTPException

Workspaces storage domain is not available

Error message

Workspaces storage domain is not available

What it means

Storage was configured, but storage.getStore('workspaces') returned null — the configured storage adapter does not provide the workspaces domain. The handler throws a 500 because it cannot proceed without a workspace store. Each storage adapter implements only the domains it supports.

Source

Thrown at packages/server/src/server/handlers/stored-workspaces.ts:52

  path: '/stored/workspaces',
  responseType: 'json',
  queryParamSchema: listStoredWorkspacesQuerySchema,
  responseSchema: listStoredWorkspacesResponseSchema,
  summary: 'List stored workspaces',
  description: 'Returns a paginated list of all workspace configurations stored in the database',
  tags: ['Stored Workspaces'],
  requiresAuth: true,
  handler: async ({ mastra, page, perPage, orderBy, authorId, metadata, requestContext }) => {
    try {
      const storage = mastra.getStorage();

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

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

      // Resolve the visibility scope for this caller. Non-owner queries for
      // another author return nothing (workspaces have no `public` visibility
      // yet); default lists return the caller's rows plus legacy unowned
      // records.
      const filter = resolveAuthorFilter({
        requestContext,
        resource: 'stored-workspaces',
        queryAuthorId: authorId,
      });

      const scope = await getStoredResourceScope(mastra, requestContext);
      const result = await workspaceStore.listResolved({
        page,
        perPage,
        orderBy,
        authorId: filter.kind === 'exact' ? filter.authorId : undefined,

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Upgrade the storage adapter package to a version supporting the workspaces domain (pnpm update @mastra/libsql etc.)
  2. Switch to a storage adapter known to support workspaces (e.g. current LibSQLStore or PgStore)
  3. If using a custom adapter, implement the workspaces store domain in getStore
  4. Verify adapter/server package versions are aligned in the workspace (pnpm why @mastra/core)

Example fix

// before (package.json)
"@mastra/libsql": "0.1.0" // predates workspaces domain
// after
"@mastra/libsql": "latest" // then pnpm install and re-init schema
Defensive patterns

Strategy: fallback

Validate before calling

import type { MastraStorage } from '@mastra/core';
export async function hasWorkspacesDomain(storage: MastraStorage): Promise<boolean> {
  return Boolean(await storage.getStore('workspaces'));
}

Type guard

function hasWorkspacesStore(s: unknown): s is { getStore: (d: 'workspaces') => Promise<unknown> } {
  return !!s && typeof (s as any).getStore === 'function';
}

Try / catch

try {
  const res = await fetch(`${baseUrl}/api/stored/workspaces`);
  if (!res.ok) throw Object.assign(new Error(await res.text()), { status: res.status });
} catch (e: any) {
  if (e.status === 500 && String(e.message).includes('Workspaces storage domain is not available')) {
    console.warn('Adapter lacks workspaces support; falling back to runtime-only workspaces');
  } else throw e;
}

Prevention

When it happens

Trigger: GET /api/stored/workspaces against a Mastra whose storage adapter lacks workspaces-domain support (older adapter version, or an adapter that implements only agents/threads/memory domains).

Common situations: Using an outdated @mastra/libsql/@mastra/pg version predating workspace stores; custom storage adapter without getStore('workspaces') support; adapter upgraded in app code but server package expects a newer one.

Related errors

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