{"record":{"id":"fb7add3b2d05bc76","repo":"mastra-ai/mastra","slug":"enoent-fb7add","errorCode":"ENOENT","errorMessage":"File not found: ${path}","messagePattern":"File not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/filesystem/local-filesystem.ts","lineNumber":404,"sourceCode":"    this.logger.debug('Reading file', { path: inputPath, encoding: options?.encoding });\n    await this.ensureReady();\n    const absolutePath = this.resolvePath(inputPath);\n    await this.assertPathContained(absolutePath);\n\n    try {\n      const stats = await fs.stat(absolutePath);\n      if (stats.isDirectory()) {\n        throw new IsDirectoryError(inputPath);\n      }\n\n      if (options?.encoding) {\n        return await fs.readFile(absolutePath, { encoding: options.encoding });\n      }\n      return await fs.readFile(absolutePath);\n    } catch (error: unknown) {\n      if (error instanceof IsDirectoryError) throw error;\n      if (isEnoentError(error)) {\n        throw new FileNotFoundError(inputPath);\n      }\n      throw error;\n    }\n  }\n\n  async writeFile(inputPath: string, content: FileContent, options?: WriteOptions): Promise<void> {\n    const contentSize = Buffer.isBuffer(content) ? content.length : content.length;\n    this.logger.debug('Writing file', { path: inputPath, size: contentSize, recursive: options?.recursive });\n    await this.ensureReady();\n    this.assertWritable('writeFile');\n    const absolutePath = this.resolvePath(inputPath);\n    await this.assertPathContained(absolutePath);\n\n    // When recursive is explicitly false, verify parent directory exists\n    if (options?.recursive === false) {\n      const dir = nodePath.dirname(absolutePath);\n      const parentPath = nodePath.dirname(inputPath);\n      try {","sourceCodeStart":386,"sourceCodeEnd":422,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/filesystem/local-filesystem.ts#L386-L422","documentation":"readFile throws FileNotFoundError (code ENOENT) when the target path does not exist on disk. The raw Node ENOENT from fs.readFile is translated into this typed error so callers can branch on error.code === 'ENOENT' or instanceof FileNotFoundError. This is one of the most common filesystem errors and usually indicates a wrong path, wrong casing, or a file that was expected to have been created earlier.","triggerScenarios":"readFile (or the 'content' helper) with a path that was never created, was deleted, or has a typo/wrong casing; reading a file expected from a previous workflow step that failed silently; case-sensitive filesystems where 'Config.JSON' ≠ 'config.json'.","commonSituations":"Agent hallucinates or misremembers a filename; file created in a different basePath or mount than where it's read; CI environment lacks a file present locally; path built from untrimmed user input (whitespace/newline in filename).","solutions":["Check existence first with stat or use list to confirm the exact filename (watch casing).","Create the file before reading it, or return a default/empty value when it is optional.","Catch FileNotFoundError (code ENOENT) and handle it as 'absent' rather than a hard failure when appropriate.","Verify the workspace basePath and mount configuration point at the directory that actually contains the file."],"exampleFix":"// before\nconst cfg = await fs.readFile('config.json', { encoding: 'utf8' }); // throws if missing\n// after\nlet cfg: string;\ntry {\n  cfg = await fs.readFile('config.json', { encoding: 'utf8' });\n} catch (e) {\n  if (e instanceof FileNotFoundError) cfg = '{}';\n  else throw e;\n}","handlingStrategy":"try-catch","validationCode":"try {\n  await ws.stat(p);\n} catch {\n  return null; // or create the file, depending on semantics\n}","typeGuard":"import { FileNotFoundError } from '@mastra/core/workspace/errors';\nfunction isFileNotFoundError(e: unknown): e is FileNotFoundError {\n  return e instanceof FileNotFoundError ||\n    (e instanceof Error && 'code' in e && (e as { code?: string }).code === 'ENOENT');\n}","tryCatchPattern":"try {\n  return await ws.readFile(p, { encoding: 'utf8' });\n} catch (e) {\n  if (isFileNotFoundError(e)) return defaultValue; // optional file\n  throw e;\n}","preventionTips":["Confirm exact filenames via list/stat — beware case sensitivity.","Create files before reading them in multi-step flows; check the producing step succeeded.","Trim and normalize user/model supplied filenames before use.","Verify basePath and mount config match where the file was actually written."],"tags":["filesystem","enoent","file-not-found"],"backgroundTag":"enoent-no-such-file","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}