{"record":{"id":"bbedf89bc6aadf7b","repo":"mastra-ai/mastra","slug":"no-workspace-filesystem-configured-bbedf8","errorCode":null,"errorMessage":"No workspace filesystem configured","messagePattern":"No workspace filesystem configured","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"error","filePath":"packages/server/src/server/handlers/workspace.ts","lineNumber":491,"sourceCode":"  path: '/workspaces/:workspaceId/fs/read',\n  responseType: 'json',\n  pathParamSchema: workspaceIdPathParams,\n  queryParamSchema: fsReadQuerySchema,\n  responseSchema: fsReadResponseSchema,\n  summary: 'Read file content',\n  description: 'Returns the content of a file at the specified path',\n  tags: ['Workspace'],\n  handler: async ({ mastra, path, encoding, workspaceId }) => {\n    try {\n      requireWorkspaceV1Support();\n\n      if (!path) {\n        throw new HTTPException(400, { message: 'Path is required' });\n      }\n\n      const workspace = await getWorkspaceById(mastra, workspaceId);\n      if (!workspace?.filesystem) {\n        throw new HTTPException(404, { message: 'No workspace filesystem configured' });\n      }\n\n      const decodedPath = decodeURIComponent(path);\n\n      // Check if path exists\n      if (!(await workspace.filesystem.exists(decodedPath))) {\n        throw new HTTPException(404, { message: `Path \"${decodedPath}\" not found` });\n      }\n\n      // Read file content\n      const content = await workspace.filesystem.readFile(decodedPath, {\n        encoding: (encoding as BufferEncoding) || 'utf-8',\n      });\n\n      return {\n        path: decodedPath,\n        content: typeof content === 'string' ? content : content.toString('utf-8'),\n        type: 'file' as const,","sourceCodeStart":473,"sourceCodeEnd":509,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/workspace.ts#L473-L509","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the workspaceId matches a workspace that has a filesystem (check workspace capabilities via the workspaces list endpoint, hasFilesystem: true).","Configure a filesystem (e.g. new WorkspaceFilesystem(...) or CompositeFilesystem) on the workspace in your Mastra setup.","Update @mastra/core to a version supporting workspace v1 filesystems if getWorkspaceById silently resolves a capability-less workspace."],"exampleFix":"// before\nnew Workspace({ id: 'w1' });\n// after\nnew Workspace({ id: 'w1', filesystem: new WorkspaceFilesystem({ root: './workspace' }) });","handlingStrategy":"type-guard","validationCode":"const ws = await getWorkspace(workspaceId);\nif (!ws?.capabilities?.hasFilesystem) {\n  throw new Error(`Workspace ${workspaceId} has no filesystem; file ops unavailable`);\n}","typeGuard":"function hasFilesystem(ws: { filesystem?: unknown } | undefined | null): ws is { filesystem: WorkspaceFilesystem } {\n  return !!ws && ws.filesystem != null;\n}","tryCatchPattern":"try {\n  return await readWorkspaceFile({ workspaceId, path });\n} catch (e) {\n  if (isHttpException(e, 404) && e.message.includes('No workspace filesystem configured')) {\n    throw new Error(`Workspace \"${workspaceId}\" does not support filesystem operations — check the workspaceId and its config`);\n  }\n  throw e;\n}","preventionTips":["Check the hasFilespaces capability via the workspaces list endpoint before file operations.","Always attach a filesystem to workspaces used by file tooling.","Centralize workspaceId constants to avoid typos resolving to wrong workspaces.","Pin/upgrade @mastra/core to a workspace-v1-capable version."],"tags":["workspace","http-404","filesystem","configuration"],"backgroundTag":"workspace-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}