{"record":{"id":"5a2324b045176bce","repo":"mastra-ai/mastra","slug":"no-workspace-filesystem-configured","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/plans.ts","lineNumber":53,"sourceCode":"    try {\n      const versionOptions = versionId ? { versionId } : status ? { status } : undefined;\n      const agent = await getAgentFromSystem({ mastra, agentId, versionOptions, requestContext });\n      const tools = await agent.listTools({ requestContext });\n      const hasSubmitPlan = Object.values(tools).some(\n        tool => typeof tool === 'object' && tool !== null && 'id' in tool && tool.id === submitPlanTool.id,\n      );\n\n      if (!hasSubmitPlan) {\n        throw new HTTPException(404, { message: 'Plan capability not found' });\n      }\n      if (!isPlanPath(path)) {\n        throw new HTTPException(400, { message: 'Invalid plan path' });\n      }\n\n      const workspace = await agent.getWorkspace({ requestContext });\n      const filesystem = await workspace?.resolveFilesystem({ requestContext });\n      if (!filesystem) {\n        throw new HTTPException(404, { message: 'No workspace filesystem configured' });\n      }\n      if (!(await filesystem.exists(path))) {\n        throw new HTTPException(404, { message: `Plan file \"${path}\" not found` });\n      }\n\n      const content = await filesystem.readFile(path, { encoding: 'utf-8' });\n      return {\n        path,\n        content: typeof content === 'string' ? content : content.toString('utf-8'),\n      };\n    } catch (error) {\n      return handleError(error, 'Error reading submitted plan');\n    }\n  },\n});\n","sourceCodeStart":35,"sourceCodeEnd":69,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/plans.ts#L35-L69","documentation":"The plans handler resolves the agent's workspace via `agent.getWorkspace()` and its filesystem via `workspace?.resolveFilesystem()`; when no workspace or filesystem is configured it throws a 404 'No workspace filesystem configured'. Plan files live in the agent's workspace, so without one the endpoint cannot operate.","triggerScenarios":"Calling plan APIs for an agent constructed without a workspace (no `workspace` option), or a workspace whose resolveFilesystem returns undefined (e.g. a workspace with no filesystem backend attached).","commonSituations":"Agents defined before workspaces were introduced and never migrated; workspace configured with only non-filesystem resources; plan UI enabled for an agent lacking workspace config; typos in workspace wiring that silently leave it undefined.","solutions":["Configure a workspace on the agent: `new Agent({ ..., workspace: createWorkspace({...}) })` with a filesystem-backed workspace.","Verify the workspace's filesystem resolver is initialized (resolveFilesystem returns a filesystem).","Confirm the correct agent ID is being used — one that actually has a workspace.","Check for runtime errors in workspace construction that could leave it undefined."],"exampleFix":"// before\nnew Agent({ name: 'planner', instructions: '...' }); // no workspace\n// after\nnew Agent({ name: 'planner', instructions: '...', workspace: myWorkspace });","handlingStrategy":"validation","validationCode":"const workspace = await agent.getWorkspace({ requestContext });\nconst fs = workspace && await workspace.resolveFilesystem({ requestContext });\nif (!fs) throw new Error('Agent has no workspace filesystem; configure one before calling plan APIs');","typeGuard":"function hasWorkspaceFilesystem(w: unknown): w is { resolveFilesystem(): Promise<unknown> } {\n  return !!w && typeof w === 'object' && 'resolveFilesystem' in w;\n}","tryCatchPattern":"try {\n  return await getPlan(agentId, path);\n} catch (e) {\n  if (e.status === 404 && e.message.includes('filesystem')) {\n    console.error('Attach a filesystem-backed workspace to the agent');\n    return null;\n  }\n  throw e;\n}","preventionTips":["Always construct plan-capable agents with a workspace option.","Smoke-test workspace.resolveFilesystem() at agent startup.","Only render plan UI when the agent config declares a workspace."],"tags":["http-404","workspace","configuration","plans"],"backgroundTag":"workspace-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}