mastra-ai/mastra · error · FilesystemNotAvailableError

NO_FILESYSTEM

NO_FILESYSTEM

Error message

Workspace does not have a filesystem configured

What it means

Thrown by requireFilesystem when the workspace exists but has no `filesystem` configured. File tools need a filesystem provider to read/write; a workspace with only a sandbox (or neither) cannot serve them. FilesystemNotAvailableError carries code NO_FILESYSTEM.

Source

Thrown at packages/core/src/workspace/tools/helpers.ts:53

 */
export function requireWorkspace(context: ToolExecutionContext): Workspace {
  if (!context?.workspace) {
    throw new WorkspaceNotAvailableError();
  }
  return context.workspace;
}

/**
 * Extract filesystem from workspace in tool execution context.
 * Throws if workspace or filesystem is not available.
 */
export function requireFilesystem(context: ToolExecutionContext): {
  workspace: Workspace;
  filesystem: WorkspaceFilesystem;
} {
  const workspace = requireWorkspace(context);
  if (!workspace.filesystem) {
    throw new FilesystemNotAvailableError();
  }
  return { workspace, filesystem: workspace.filesystem };
}

/**
 * Extract sandbox from workspace in tool execution context.
 * Throws if workspace or sandbox is not available.
 */
export function requireSandbox(context: ToolExecutionContext): {
  workspace: Workspace;
  sandbox: WorkspaceSandbox;
} {
  const workspace = requireWorkspace(context);
  if (!workspace.sandbox) {
    throw new SandboxNotAvailableError();
  }
  return { workspace, sandbox: workspace.sandbox };
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Add a filesystem provider to the workspace: `new Workspace({ filesystem: createFilesystem({ root }) })`
2. Only register/expose file tools when `workspace.filesystem` is set
3. Check `workspace.filesystem` before executing file operations in custom code
4. Catch NO_FILESYSTEM and fall back to sandbox shell commands if appropriate

Example fix

// before
new Workspace({ sandbox })
// after
new Workspace({ sandbox, filesystem: createFilesystem({ root: process.cwd() }) })

if (!workspace.filesystem) {
  throw new Error('File tools require a workspace filesystem');
}

function hasFilesystem(w: Workspace): w is Workspace & { filesystem: WorkspaceFilesystem } {
  return !!w.filesystem;
}

try {
  return await fileTool.execute(ctx);
} catch (e: any) {
  if (e?.code === 'NO_FILESYSTEM' || /filesystem configured/i.test(e?.message ?? '')) {
    return { error: 'Add a filesystem to the workspace to use file tools.' };
  }
  throw e;
}

When it happens

Trigger: Invoking file tools (read/write/edit/delete/list) on a workspace constructed without a filesystem, e.g. `new Workspace({ sandbox })` only.

Common situations: Configuring a workspace for shell/computer use only and later adding file tools; removing the filesystem option during refactors; assuming a sandbox implies filesystem access.

Related errors

• CompositeFilesystem requires at least one mount
• Nested mount paths are not supported: "${b}" is nested under
• READ_ONLY
• NO_WORKSPACE
• NO_SANDBOX

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