mastra-ai/mastra · error · HTTPException

No workspace filesystem configured

Error message

No workspace filesystem configured

What it means

Thrown (HTTP 404) by the workspace file read handler when the workspace identified by workspaceId is found but has no filesystem configured. Workspace filesystem capability is optional, so read requests against a filesystem-less workspace cannot be served. Often a symptom of using the wrong workspaceId or a workspace created without a filesystem.

Source

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

  path: '/workspaces/:workspaceId/fs/read',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  queryParamSchema: fsReadQuerySchema,
  responseSchema: fsReadResponseSchema,
  summary: 'Read file content',
  description: 'Returns the content of a file at the specified path',
  tags: ['Workspace'],
  handler: async ({ mastra, path, encoding, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!path) {
        throw new HTTPException(400, { message: 'Path is required' });
      }

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace?.filesystem) {
        throw new HTTPException(404, { message: 'No workspace filesystem configured' });
      }

      const decodedPath = decodeURIComponent(path);

      // Check if path exists
      if (!(await workspace.filesystem.exists(decodedPath))) {
        throw new HTTPException(404, { message: `Path "${decodedPath}" not found` });
      }

      // Read file content
      const content = await workspace.filesystem.readFile(decodedPath, {
        encoding: (encoding as BufferEncoding) || 'utf-8',
      });

      return {
        path: decodedPath,
        content: typeof content === 'string' ? content : content.toString('utf-8'),
        type: 'file' as const,

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the workspaceId matches a workspace that has a filesystem (check workspace capabilities via the workspaces list endpoint, hasFilesystem: true).
2. Configure a filesystem (e.g. new WorkspaceFilesystem(...) or CompositeFilesystem) on the workspace in your Mastra setup.
3. Update @mastra/core to a version supporting workspace v1 filesystems if getWorkspaceById silently resolves a capability-less workspace.

Example fix

// before
new Workspace({ id: 'w1' });
// after
new Workspace({ id: 'w1', filesystem: new WorkspaceFilesystem({ root: './workspace' }) });

const ws = await getWorkspace(workspaceId);
if (!ws?.capabilities?.hasFilesystem) {
  throw new Error(`Workspace ${workspaceId} has no filesystem; file ops unavailable`);
}

function hasFilesystem(ws: { filesystem?: unknown } | undefined | null): ws is { filesystem: WorkspaceFilesystem } {
  return !!ws && ws.filesystem != null;
}

try {
  return await readWorkspaceFile({ workspaceId, path });
} catch (e) {
  if (isHttpException(e, 404) && e.message.includes('No workspace filesystem configured')) {
    throw new Error(`Workspace "${workspaceId}" does not support filesystem operations — check the workspaceId and its config`);
  }
  throw e;
}

When it happens

Trigger: GET file read on a workspace whose constructor/registry entry has no filesystem attached — e.g. an agent-owned workspace without filesystem capability, a typo'd workspaceId resolving to a different workspace, or an older @mastra/core version where the workspace doesn't expose filesystem.

Common situations: Pointing tooling at an agent workspace that only has sandbox/vector capabilities; forgetting to pass a filesystem to the Workspace constructor; @mastra/core version downgrade dropping workspace v1 filesystem support.

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/bbedf89bc6aadf7b. Report an issue: GitHub.