mastra-ai/mastra · error · HTTPException

Workspace filesystem not available

Error message

Workspace filesystem not available

What it means

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.

Source

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

  path: '/workspaces/:workspaceId/skills-sh/install',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  bodySchema: skillsShInstallBodySchema,
  responseSchema: skillsShInstallResponseSchema,
  summary: 'Install skill from Skills API',
  description: 'Installs a skill by fetching files from the Skills API and writing to workspace filesystem.',
  tags: ['Workspace', 'Skills'],
  handler: async ({ mastra, workspaceId, owner, repo, skillName, mount }) => {
    try {
      requireWorkspaceV1Support();

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace) {
        throw new HTTPException(404, { message: 'Workspace not found' });
      }

      if (!workspace.filesystem) {
        throw new HTTPException(400, { message: 'Workspace filesystem not available' });
      }

      if (workspace.filesystem.readOnly) {
        throw new HTTPException(403, { message: 'Workspace is read-only' });
      }

      // Fetch skill files from the Skills API
      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}.`,
        });
      }

      // Validate skill name to prevent path traversal
      const safeSkillId = assertSafeSkillName(result.skillId);
      const installPath = buildSkillInstallPath(workspace.filesystem, safeSkillId, mount);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Create or re-create the workspace with filesystem support enabled.
2. Pick a different workspace that has a filesystem attached.
3. Upgrade/reconcile the workspace so its provider mounts a filesystem, then retry the install.

Example fix

// before
const ws = await createWorkspace({ name: 'w', /* no filesystem option */ });
// after
const ws = await createWorkspace({ name: 'w', filesystem: { enabled: true } });

const ws = await getWorkspace(workspaceId);
if (!ws?.filesystem) throw new Error('Selected workspace has no filesystem; use a FS-enabled workspace for skill installs.');

function hasFilesystem(ws: unknown): ws is { id: string; filesystem: NonNullable<unknown> } {
  return !!ws && (ws as any).filesystem != null;
}

try {
  await installSkill({ workspaceId, ... });
} catch (e) {
  if (/filesystem not available/.test(String(e))) {
    throw new Error('Recreate the workspace with filesystem support enabled.');
  }
  throw e;
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• CompositeFilesystem requires at least one mount
• Nested mount paths are not supported: "${b}" is nested under
• READ_ONLY
• NO_FILESYSTEM
• No workspace filesystem configured

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