{"record":{"id":"ed89e2ff4b94d097","repo":"mastra-ai/mastra","slug":"workspace-v1-not-supported-by-this-version-of-mas","errorCode":null,"errorMessage":"Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.","messagePattern":"Workspace v1 not supported by this version of @mastra/core\\. Please upgrade to a newer version\\.","errorType":"http","errorClass":"HTTPException","httpStatus":501,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":138,"sourceCode":" */\nfunction handleWorkspaceError(error: unknown, defaultMessage: string): never {\n  if (isFilesystemNotFoundError(error)) {\n    const message = error instanceof Error ? error.message : 'Not found';\n    throw new HTTPException(404, { message });\n  }\n  if (isFilesystemPermissionError(error)) {\n    const message = error instanceof Error ? error.message : 'Permission denied';\n    throw new HTTPException(403, { message });\n  }\n  return handleError(error, defaultMessage);\n}\n\n/**\n * Throws if workspace v1 is not supported by the current version of @mastra/core.\n */\nfunction requireWorkspaceV1Support(): void {\n  if (!coreFeatures.has('workspaces-v1')) {\n    throw new HTTPException(501, {\n      message: 'Workspace v1 not supported by this version of @mastra/core. Please upgrade to a newer version.',\n    });\n  }\n}\n\n/**\n * Get a workspace by ID from Mastra's workspace registry.\n *\n * Backwards compatible: Falls back to searching through agents if\n * mastra.getWorkspaceById() is not available (older @mastra/core versions).\n */\nasync function getWorkspaceById(mastra: any, workspaceId: string): Promise<Workspace | undefined> {\n  requireWorkspaceV1Support();\n\n  // Check if the global workspace matches\n  const globalWorkspace = mastra.getWorkspace?.();\n  if (globalWorkspace?.id === workspaceId) {\n    return globalWorkspace;","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L120-L156","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade @mastra/core to a version that supports workspaces v1 (matching your @mastra/server release)","Run pnpm why @mastra-core / inspect the lockfile to eliminate duplicated mismatched core versions","Rebuild and redeploy after aligning versions"],"exampleFix":"// before\n\"@mastra/core\": \"0.10.5\", \"@mastra/server\": \"0.12.0\"\n// after\n\"@mastra/core\": \"0.12.0\", \"@mastra/server\": \"0.12.0\"","handlingStrategy":"validation","validationCode":"const { coreFeatures } = await import('@mastra/core'); if (!coreFeatures?.has('workspaces-v1')) throw new Error('Upgrade @mastra/core to use workspace v1 endpoints');","typeGuard":"const supportsWorkspacesV1 = (f: Set<string> | undefined): boolean => !!f?.has('workspaces-v1');","tryCatchPattern":"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; }","preventionTips":["Upgrade all @mastra/* packages together","Check feature availability before using new API surfaces in deployments","Review the changelog for feature-flag-gated APIs when upgrading"],"tags":["http-501","version-mismatch","workspaces"],"backgroundTag":"version-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}