mastra-ai/mastra · error · HTTPException

Path "${decodedPath}" not found

Error message

Path "${decodedPath}" not found

What it means

Thrown (HTTP 404) by the workspace file read handler when the decoded path does not exist in the workspace filesystem, as determined by filesystem.exists() before reading. This is the standard 'file not found' error for workspace file reads, reported with the exact decoded path to aid debugging.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:498

  tags: ['Workspace'],
  handler: async ({ mastra, path, encoding, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!path) {
        throw new HTTPException(400, { message: 'Path is required' });
      }

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace?.filesystem) {
        throw new HTTPException(404, { message: 'No workspace filesystem configured' });
      }

      const decodedPath = decodeURIComponent(path);

      // Check if path exists
      if (!(await workspace.filesystem.exists(decodedPath))) {
        throw new HTTPException(404, { message: `Path "${decodedPath}" not found` });
      }

      // Read file content
      const content = await workspace.filesystem.readFile(decodedPath, {
        encoding: (encoding as BufferEncoding) || 'utf-8',
      });

      return {
        path: decodedPath,
        content: typeof content === 'string' ? content : content.toString('utf-8'),
        type: 'file' as const,
      };
    } catch (error) {
      return handleWorkspaceError(error, 'Error reading file');
    }
  },
});

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Confirm the file exists relative to the workspace filesystem root; list the directory via the workspace list endpoint to see actual entries.
  2. Fix path casing/spelling — mounts are typically case-sensitive.
  3. If the file is generated, ensure the producing step/workflow completed before reading.
  4. Check for double URL-encoding: pass the path encoded once with encodeURIComponent.

Example fix

// before
const p = '/absolute/host/path/output.json';
// after (workspace-relative path that exists)
const p = 'output.json';
Defensive patterns

Strategy: validation

Validate before calling

const entries = await listWorkspaceDir({ workspaceId, path: dirname(p) });
if (!entries.some(e => e.path === p)) {
  throw new Error(`File "${p}" does not exist in workspace ${workspaceId}`);
}

Type guard

function fileExistsIn(entries: { path: string }[], p: string): boolean {
  return entries.some(e => e.path === p || e.path === p.replace(/^\//, ''));
}

Try / catch

try {
  return await readWorkspaceFile({ workspaceId, path: p });
} catch (e) {
  if (isHttpException(e, 404) && e.message.includes('not found')) {
    const listing = await listWorkspaceDir({ workspaceId, path: dirname(p) });
    throw new Error(`File "${p}" not found. Nearby entries: ${listing.map(e => e.path).join(', ')}`);
  }
  throw e;
}

Prevention

When it happens

Trigger: GET file read with a path that doesn't exist — typos, wrong case on case-sensitive mounts, path relative to the wrong root, reading a file before it's written, or double-encoding issues where the decoded path isn't the intended one.

Common situations: Race with a workflow that hasn't produced the file yet; referencing files outside the workspace root (paths are workspace-relative, not host-absolute); Git checkout differences deleting generated artifacts.

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/1aadaadc46f6baca. Report an issue: GitHub.