{"record":{"id":"e277bb32c5dd3b5f","repo":"mastra-ai/mastra","slug":"missing-required-file-checked-the-following-paths","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/cli/src/services/service.file.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  public replaceValuesInFile({\n    filePath,\n    replacements,\n  }: {\n    filePath: string;\n    replacements: { search: string; replace: string }[];\n  }) {\n    let fileContent = fs.readFileSync(filePath, 'utf8');\n    replacements.forEach(({ search, replace }) => {\n      fileContent = fileContent.replaceAll(search, replace);\n    });\n\n    fs.writeFileSync(filePath, fileContent);\n  }\n}\n","sourceCodeStart":31,"sourceCodeEnd":67,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/services/service.file.ts#L31-L67","documentation":"FileEnvService.getFirstExistingFile throws this when none of the candidate file paths exist on disk. The CLI uses it (via getMastraEntryFile, mastraEntryFile, entryFile) to locate required files such as the Mastra entry file by trying each candidate path in order. If the loop exhausts all candidates, the required file is considered missing and it throws with the full list of paths checked.","triggerScenarios":"Running a CLI command in a directory where the expected file was never created, the project was run from the wrong working directory, a custom path/flag points to a nonexistent file, or the file was deleted/renamed (e.g. index.ts vs index.js mismatch after switching module systems).","commonSituations":"Executing `mastra dev`/`mastra build` outside the project root; a fresh clone missing generated files; renaming the entry file without updating mastra config; TypeScript-to-JS or ESM/CJS migration changing the expected filename extension.","solutions":["Create the missing file at one of the listed paths (e.g. src/mastra/index.ts)","cd into the project root before running the CLI so relative candidate paths resolve","Pass the correct custom entry-file path/flag if your layout differs from the default","Verify the file exists: `ls` the paths from the error message; restore it if deleted"],"exampleFix":"// before (file missing)\nmastra dev\n// Error: Missing required file, checked the following paths: ...\n// after\nmkdir -p src/mastra && echo \"export const mastra = new Mastra()\" > src/mastra/index.ts\nmastra dev","handlingStrategy":"fallback","validationCode":"import fs from 'node:fs';\nconst candidates = ['src/mastra/index.ts', 'index.ts'];\nif (!candidates.some(f => fs.existsSync(f))) {\n  throw new Error(`No Mastra entry file found; expected one of: ${candidates.join(', ')}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await runCli(['dev']);\n} catch (e) {\n  if (e instanceof Error && e.message.startsWith('Missing required file')) {\n    console.error('Run from the project root and ensure the Mastra entry file exists (e.g. src/mastra/index.ts).');\n    process.exitCode = 1;\n  } else throw e;\n}","preventionTips":["Run Mastra CLI commands from the project root","Scaffold the entry file with `mastra init` before running dev/build","Keep the entry filename/extension consistent with your module system and config","Check existence of required files in scripts with fs.existsSync before invoking the CLI"],"tags":["filesystem","missing-file","cli"],"backgroundTag":"missing-required-file","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}