mastra-ai/mastra · error · FileNotFoundError

ENOENT

ENOENT

Error message

File not found: ${path}

What it means

fsStat in fs-utils wraps a low-level stat call; when the underlying filesystem reports ENOENT it rethrows it as FileNotFoundError with message "File not found: <path>". The library normalizes platform-specific ENOENT errors into a single predictable error type for callers.

Source

Thrown at packages/core/src/workspace/filesystem/fs-utils.ts:338

 * @param absolutePath - The absolute path to stat
 * @param userPath - The user-facing path for error messages
 * @returns File stat information
 * @throws {FileNotFoundError} if path doesn't exist
 */
export async function fsStat(absolutePath: string, userPath: string): Promise<FsStatResult> {
  try {
    const stats = await fs.stat(absolutePath);
    return {
      name: path.basename(absolutePath),
      type: stats.isDirectory() ? 'directory' : 'file',
      size: stats.size,
      createdAt: stats.birthtime,
      modifiedAt: stats.mtime,
      mimeType: stats.isFile() ? getMimeType(absolutePath) : undefined,
    };
  } catch (error: unknown) {
    if (isEnoentError(error)) {
      throw new FileNotFoundError(userPath);
    }
    throw error;
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Check fs.existsSync()/await fs.exists(path) before stat, or handle FileNotFoundError.
2. Verify the configured basePath and that the path is correctly joined/normalized.
3. If the file should exist, re-run the producing step; if deletion is expected, treat this as a normal miss.

Example fix

// before
const s = await fsStat(workspace, './build/out.json');
// after
if (await workspaceExists(workspace, './build/out.json')) {
  const s = await fsStat(workspace, './build/out.json');
} else {
  throw new Error('Build output missing; run the build first');
}

if (!(await fsExists(path))) return null; // skip stat for known-missing files

try {
  return await fsStat(path);
} catch (e) {
  if (e instanceof Error && /File not found/i.test(e.message)) {
    return null; // treat as missing file
  }
  throw e;
}

When it happens

Trigger: Calling stat()/stats()/result() on a path that does not exist on disk: file deleted between listing and stat, wrong basePath configured, case-sensitivity mismatch on Linux, symlink to a missing target.

Common situations: Race conditions where a temp file was cleaned up before stat; relative path resolved against the wrong workspace base; typos in filenames; CI environments where fixtures were never written.

Related errors

• ENOENT
• FileNotFoundError: ${path}
• Presets file not found: ${absolutePath}
• MASTRA_ENTRY_FILE_NOT_FOUND
• Failed to copy studio assets from "${studioSource}" to "${st

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