mastra-ai/mastra · error · HTTPException

Workspace v1 not supported by this version of @mastra/core.

Error message

Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.

What it means

Thrown with HTTP 501 by requireWorkspaceV1Support when the installed @mastra/core build does not expose the 'workspaces-v1' feature flag. The server serves workspace routes only when core supports the workspaces v1 API; an older core makes all workspace routes unavailable by design.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:138

 */
function handleWorkspaceError(error: unknown, defaultMessage: string): never {
  if (isFilesystemNotFoundError(error)) {
    const message = error instanceof Error ? error.message : 'Not found';
    throw new HTTPException(404, { message });
  }
  if (isFilesystemPermissionError(error)) {
    const message = error instanceof Error ? error.message : 'Permission denied';
    throw new HTTPException(403, { message });
  }
  return handleError(error, defaultMessage);
}

/**
 * Throws if workspace v1 is not supported by the current version of @mastra/core.
 */
function requireWorkspaceV1Support(): void {
  if (!coreFeatures.has('workspaces-v1')) {
    throw new HTTPException(501, {
      message: 'Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.',
    });
  }
}

/**
 * Get a workspace by ID from Mastra's workspace registry.
 *
 * Backwards compatible: Falls back to searching through agents if
 * mastra.getWorkspaceById() is not available (older @mastra/core versions).
 */
async function getWorkspaceById(mastra: any, workspaceId: string): Promise<Workspace | undefined> {
  requireWorkspaceV1Support();

  // Check if the global workspace matches
  const globalWorkspace = mastra.getWorkspace?.();
  if (globalWorkspace?.id === workspaceId) {
    return globalWorkspace;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Upgrade @mastra/core to a version that supports workspaces v1 (matching your @mastra/server release)
2. Run pnpm why @mastra-core / inspect the lockfile to eliminate duplicated mismatched core versions
3. Rebuild and redeploy after aligning versions

Example fix

// before
"@mastra/core": "0.10.5", "@mastra/server": "0.12.0"
// after
"@mastra/core": "0.12.0", "@mastra/server": "0.12.0"

const { coreFeatures } = await import('@mastra/core'); if (!coreFeatures?.has('workspaces-v1')) throw new Error('Upgrade @mastra/core to use workspace v1 endpoints');

const supportsWorkspacesV1 = (f: Set<string> | undefined): boolean => !!f?.has('workspaces-v1');

try { await client.listWorkspaces(); } catch (e) { if (isHttpException(e, 501)) console.error('Upgrade @mastra/core to a version with workspaces v1 support'); else throw e; }

When it happens

Trigger: Running @mastra/server (or playground) at a newer version than @mastra/core; pinning an old core version while upgrading server handlers; mismatched monorepo/workspace dependency resolution.

Common situations: Partial upgrades where lockfiles resolve @mastra/core to an older cached version; long-lived deployments not upgraded alongside the server package; pre-release channels where the feature flag was added later.

Related errors

• Channels require a newer version of @mastra/core
• New observability endpoints require @mastra/core >= 1.13.2,
• No relevance score found in VoyageAI response
• workflowDefinitions storage domain is not available.
• AGENT_GENERATE_V1_MODEL_NOT_SUPPORTED

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