{"record":{"id":"b8c15ba50c3955ca","repo":"mastra-ai/mastra","slug":"workspace-filesystem-not-available","errorCode":null,"errorMessage":"Workspace filesystem not available","messagePattern":"Workspace filesystem not available","errorType":"http","errorClass":"HTTPException","httpStatus":400,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":1430,"sourceCode":"  path: '/workspaces/:workspaceId/skills-sh/install',\n  responseType: 'json',\n  pathParamSchema: workspaceIdPathParams,\n  bodySchema: skillsShInstallBodySchema,\n  responseSchema: skillsShInstallResponseSchema,\n  summary: 'Install skill from Skills API',\n  description: 'Installs a skill by fetching files from the Skills API and writing to workspace filesystem.',\n  tags: ['Workspace', 'Skills'],\n  handler: async ({ mastra, workspaceId, owner, repo, skillName, mount }) => {\n    try {\n      requireWorkspaceV1Support();\n\n      const workspace = await getWorkspaceById(mastra, workspaceId);\n      if (!workspace) {\n        throw new HTTPException(404, { message: 'Workspace not found' });\n      }\n\n      if (!workspace.filesystem) {\n        throw new HTTPException(400, { message: 'Workspace filesystem not available' });\n      }\n\n      if (workspace.filesystem.readOnly) {\n        throw new HTTPException(403, { message: 'Workspace is read-only' });\n      }\n\n      // Fetch skill files from the Skills API\n      const result = await fetchSkillFiles(owner, repo, skillName);\n      if (!result || result.files.length === 0) {\n        throw new HTTPException(404, {\n          message: `Could not find skill \"${skillName}\" in ${owner}/${repo}.`,\n        });\n      }\n\n      // Validate skill name to prevent path traversal\n      const safeSkillId = assertSafeSkillName(result.skillId);\n      const installPath = buildSkillInstallPath(workspace.filesystem, safeSkillId, mount);\n","sourceCodeStart":1412,"sourceCodeEnd":1448,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L1412-L1448","documentation":"HTTPException 400 thrown when the workspace exists but has no filesystem attached (workspace.filesystem is undefined/null). Skill installation needs a writable workspace filesystem, so the handler refuses to proceed.","triggerScenarios":"Calling the install-skill endpoint against a workspace created without a filesystem (e.g. a purely remote/ephemeral workspace type or one created before filesystem support).","commonSituations":"Workspaces provisioned by older tooling without the filesystem capability; workspace type that does not mount a FS; misconfiguration in workspace creation options omitting the filesystem.","solutions":["Create or re-create the workspace with filesystem support enabled.","Pick a different workspace that has a filesystem attached.","Upgrade/reconcile the workspace so its provider mounts a filesystem, then retry the install."],"exampleFix":"// before\nconst ws = await createWorkspace({ name: 'w', /* no filesystem option */ });\n// after\nconst ws = await createWorkspace({ name: 'w', filesystem: { enabled: true } });","handlingStrategy":"validation","validationCode":"const ws = await getWorkspace(workspaceId);\nif (!ws?.filesystem) throw new Error('Selected workspace has no filesystem; use a FS-enabled workspace for skill installs.');","typeGuard":"function hasFilesystem(ws: unknown): ws is { id: string; filesystem: NonNullable<unknown> } {\n  return !!ws && (ws as any).filesystem != null;\n}","tryCatchPattern":"try {\n  await installSkill({ workspaceId, ... });\n} catch (e) {\n  if (/filesystem not available/.test(String(e))) {\n    throw new Error('Recreate the workspace with filesystem support enabled.');\n  }\n  throw e;\n}","preventionTips":["Create workspaces with filesystem support explicitly enabled when skills will be installed.","Filter workspace pickers to FS-enabled workspaces for install flows.","Check workspace capabilities after upgrade/migration — older workspaces may lack the FS."],"tags":["http-400","workspace","filesystem","configuration"],"backgroundTag":"workspace-filesystem-unavailable","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}