{"record":{"id":"22459d12e550f0b5","repo":"mastra-ai/mastra","slug":"missing-required-file-checked-the-following-paths-22459d","errorCode":null,"errorMessage":"Missing required file, checked the following paths: ${files.join(', ')}","messagePattern":"Missing required file, checked the following paths: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/deployer/src/services/fs.ts","lineNumber":49,"sourceCode":"  }\n\n  public async setupEnvFile({ dbUrl }: { dbUrl: string }) {\n    const envPath = path.join(process.cwd(), '.env.development');\n\n    await fsExtra.ensureFile(envPath);\n\n    const fileEnvService = new FileEnvService(envPath);\n    await fileEnvService.setEnvValue('DB_URL', dbUrl);\n  }\n\n  public getFirstExistingFile(files: string[]): string {\n    for (const f of files) {\n      if (fs.existsSync(f)) {\n        return f;\n      }\n    }\n\n    throw new Error('Missing required file, checked the following paths: ' + files.join(', '));\n  }\n\n  /**\n   * Returns every existing file from the provided array in the same order.\n   * Callers supply files from the lowest to highest precedence so later dotenv\n   * files override earlier values when the bundler loads them.\n   */\n  public getExistingFiles(files: string[]): string[] {\n    return files.filter(file => fs.existsSync(file));\n  }\n\n  /**\n   * Returns the first existing file from the provided array, or undefined if none exist\n   * @param files array of file paths to check\n   * @returns the first existing file path or undefined\n   */\n  public getFirstExistingFileOrUndefined(files: string[]): string | undefined {\n    for (const f of files) {","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/deployer/src/services/fs.ts#L31-L67","documentation":"The deployer's fs service throws this when none of the candidate file paths supplied to getFirstExistingFile exist on disk. The function walks the array in order and returns the first path that passes fs.existsSync; if every candidate is missing it fails fast with the full list of checked paths so the developer can see exactly what was searched. Callers use it to locate required Mastra entry files and dotenv files during bundling, so this error means the project layout is missing a required artifact.","triggerScenarios":"Calling getMastraEntryFile, mastraEntryFile, or entryFile when none of the conventional entry paths (e.g. src/mastra/index.ts, mastra/index.ts) exist in the deploy target directory; running the deployer or build from the wrong working directory; deleting or renaming the Mastra entry file after scaffolding.","commonSituations":"Running `mastra deploy` or `mastra build` from a subdirectory instead of the project root; a monorepo where the entry file lives in a different package; typos in a custom --dir flag; a fresh checkout where the generated entry file was never created because `mastra init` was skipped.","solutions":["Create the Mastra entry file at one of the expected paths listed in the error message (typically src/mastra/index.ts or mastra/index.ts) exporting a Mastra instance","Re-run the command from the project root (or pass the correct --dir / cwd option) so the checked paths resolve","Check the comma-separated paths in the error and confirm the file exists at one of them, fixing the filename or extension casing","If using a custom entry location, pass it explicitly via the CLI/config option the caller supports instead of relying on defaults"],"exampleFix":"// before (project root, no entry file)\nsrc/index.ts  // Mastra instance lives here, deployer can't find it\n\n// after\nmkdir -p src/mastra\ncat > src/mastra/index.ts <<'EOF'\nimport { Mastra } from '@mastra/core/mastra';\nexport const mastra = new Mastra({});\nEOF","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nconst candidates = ['src/mastra/index.ts', 'mastra/index.ts', 'index.ts'];\nconst found = candidates.find(f => fs.existsSync(f));\nif (!found) throw new Error(`Mastra entry file missing; checked: ${candidates.join(', ')}`);","typeGuard":"function hasMastraEntry(dir: string): boolean {\n  return ['src/mastra/index.ts', 'mastra/index.ts', 'index.ts'].some(f => fs.existsSync(path.join(dir, f)));\n}","tryCatchPattern":"try {\n  const entry = getMastraEntryFile(dir);\n} catch (err) {\n  if ((err as Error).message.startsWith('Missing required file')) {\n    console.error('No Mastra entry found. Run `mastra init` or check --dir.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Run deploy/build commands from the project root, or pass the correct --dir","Keep the Mastra entry file at the conventional src/mastra/index.ts path","Commit the entry file so fresh clones work","Read the comma-separated path list in the error — it tells you exactly where it looked"],"tags":["deployer","filesystem","missing-file","build"],"backgroundTag":"missing-required-file","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}