mastra-ai/mastra · warning · HTTPException

Plan file "${path}" not found

Error message

Plan file "${path}" not found

What it means

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.

Source

Thrown at packages/server/src/server/handlers/plans.ts:56

      const tools = await agent.listTools({ requestContext });
      const hasSubmitPlan = Object.values(tools).some(
        tool => typeof tool === 'object' && tool !== null && 'id' in tool && tool.id === submitPlanTool.id,
      );

      if (!hasSubmitPlan) {
        throw new HTTPException(404, { message: 'Plan capability not found' });
      }
      if (!isPlanPath(path)) {
        throw new HTTPException(400, { message: 'Invalid plan path' });
      }

      const workspace = await agent.getWorkspace({ requestContext });
      const filesystem = await workspace?.resolveFilesystem({ requestContext });
      if (!filesystem) {
        throw new HTTPException(404, { message: 'No workspace filesystem configured' });
      }
      if (!(await filesystem.exists(path))) {
        throw new HTTPException(404, { message: `Plan file "${path}" not found` });
      }

      const content = await filesystem.readFile(path, { encoding: 'utf-8' });
      return {
        path,
        content: typeof content === 'string' ? content : content.toString('utf-8'),
      };
    } catch (error) {
      return handleError(error, 'Error reading submitted plan');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Trigger a plan run (agent plan/submit-plan flow) so the plan file is written before reading it.
  2. Confirm the workspace storage backend persists across restarts and points at the expected database.
  3. Verify you're querying the agent whose workspace actually contains the plan file.
  4. Handle 404 client-side as 'no plan yet' rather than an error.

Example fix

// before
const plan = await getPlan('agent-1', 'plan.md'); // 404 if never written
// after
const res = await getPlanSafe('agent-1', 'plan.md');
const plan = res.ok ? await res.json() : null; // render 'no plan yet' state
Defensive patterns

Strategy: fallback

Validate before calling

const workspace = await agent.getWorkspace({ requestContext });
const fs = await workspace?.resolveFilesystem({ requestContext });
if (!fs || !(await fs.exists(path))) return null; // no plan written yet

Type guard

function isPlanContent(c: unknown): c is { path: string; content: string } {
  return !!c && typeof c === 'object' && typeof (c as any).content === 'string';
}

Try / catch

try {
  return await getPlan(agentId, path);
} catch (e) {
  if (is404(e)) return null; // render 'no plan yet' state
  throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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