mastra-ai/mastra · error · HTTPException

No workspace filesystem configured

Error message

No workspace filesystem configured

What it means

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.

Source

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

    try {
      const versionOptions = versionId ? { versionId } : status ? { status } : undefined;
      const agent = await getAgentFromSystem({ mastra, agentId, versionOptions, requestContext });
      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. Configure a workspace on the agent: `new Agent({ ..., workspace: createWorkspace({...}) })` with a filesystem-backed workspace.
2. Verify the workspace's filesystem resolver is initialized (resolveFilesystem returns a filesystem).
3. Confirm the correct agent ID is being used — one that actually has a workspace.
4. Check for runtime errors in workspace construction that could leave it undefined.

Example fix

// before
new Agent({ name: 'planner', instructions: '...' }); // no workspace
// after
new Agent({ name: 'planner', instructions: '...', workspace: myWorkspace });

const workspace = await agent.getWorkspace({ requestContext });
const fs = workspace && await workspace.resolveFilesystem({ requestContext });
if (!fs) throw new Error('Agent has no workspace filesystem; configure one before calling plan APIs');

function hasWorkspaceFilesystem(w: unknown): w is { resolveFilesystem(): Promise<unknown> } {
  return !!w && typeof w === 'object' && 'resolveFilesystem' in w;
}

try {
  return await getPlan(agentId, path);
} catch (e) {
  if (e.status === 404 && e.message.includes('filesystem')) {
    console.error('Attach a filesystem-backed workspace to the agent');
    return null;
  }
  throw e;
}

When it happens

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

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

Related errors

• Plan file "${path}" not found
• No workspace filesystem configured
• No workspace configured
• No workspace with skills configured
• Skill not found: ${invocation.skillName}.

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