{"record":{"id":"9c0fec42b7f0676a","repo":"mastra-ai/mastra","slug":"plan-file-path-not-found","errorCode":null,"errorMessage":"Plan file \"${path}\" not found","messagePattern":"Plan file \"(.+?)\" not found","errorType":"http","errorClass":"HTTPException","httpStatus":404,"severity":"warning","filePath":"packages/server/src/server/handlers/plans.ts","lineNumber":56,"sourceCode":"      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":38,"sourceCodeEnd":69,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/server/src/server/handlers/plans.ts#L38-L69","documentation":"Once a workspace filesystem is resolved, the plans handler checks `filesystem.exists(path)` and throws a 404 `Plan file \"${path}\" not found` when the plan file hasn't been created yet. The path was valid, but no file exists at that location in the workspace.","triggerScenarios":"Reading a plan file before the agent ever wrote one; the agent's submit-plan run failed or wrote to a different path; the workspace storage was reset/cleared; requesting a plan for a different agent whose workspace lacks that file.","commonSituations":"UI fetching the plan on page load before the first plan run; plan generation aborted mid-run leaving no file; pointing at a fresh environment with an empty workspace database; deleting the file manually or via cleanup jobs.","solutions":["Trigger a plan run (agent plan/submit-plan flow) so the plan file is written before reading it.","Confirm the workspace storage backend persists across restarts and points at the expected database.","Verify you're querying the agent whose workspace actually contains the plan file.","Handle 404 client-side as 'no plan yet' rather than an error."],"exampleFix":"// before\nconst plan = await getPlan('agent-1', 'plan.md'); // 404 if never written\n// after\nconst res = await getPlanSafe('agent-1', 'plan.md');\nconst plan = res.ok ? await res.json() : null; // render 'no plan yet' state","handlingStrategy":"fallback","validationCode":"const workspace = await agent.getWorkspace({ requestContext });\nconst fs = await workspace?.resolveFilesystem({ requestContext });\nif (!fs || !(await fs.exists(path))) return null; // no plan written yet","typeGuard":"function isPlanContent(c: unknown): c is { path: string; content: string } {\n  return !!c && typeof c === 'object' && typeof (c as any).content === 'string';\n}","tryCatchPattern":"try {\n  return await getPlan(agentId, path);\n} catch (e) {\n  if (is404(e)) return null; // render 'no plan yet' state\n  throw e;\n}","preventionTips":["Run the plan-generation flow before requesting the plan file.","Persist workspace storage so plans survive restarts.","Treat 'plan not found' as a normal pre-first-run state in the UI."],"tags":["http-404","workspace","plans","filesystem"],"backgroundTag":"file-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}