mastra-ai/mastra · error · Error

Missing required file, checked the following paths: ${files.

Error message

Missing required file, checked the following paths: ${files.join(', ')}

What it means

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.

Source

Thrown at packages/cli/src/services/service.file.ts:49

  }

  public async setupEnvFile({ dbUrl }: { dbUrl: string }) {
    const envPath = path.join(process.cwd(), '.env.development');

    await fsExtra.ensureFile(envPath);

    const fileEnvService = new FileEnvService(envPath);
    await fileEnvService.setEnvValue('DB_URL', dbUrl);
  }

  public getFirstExistingFile(files: string[]): string {
    for (const f of files) {
      if (fs.existsSync(f)) {
        return f;
      }
    }

    throw new Error('Missing required file, checked the following paths: ' + files.join(', '));
  }

  public replaceValuesInFile({
    filePath,
    replacements,
  }: {
    filePath: string;
    replacements: { search: string; replace: string }[];
  }) {
    let fileContent = fs.readFileSync(filePath, 'utf8');
    replacements.forEach(({ search, replace }) => {
      fileContent = fileContent.replaceAll(search, replace);
    });

    fs.writeFileSync(filePath, fileContent);
  }
}

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before (file missing)
mastra dev
// Error: Missing required file, checked the following paths: ...
// after
mkdir -p src/mastra && echo "export const mastra = new Mastra()" > src/mastra/index.ts
mastra dev

Defensive patterns

Strategy: fallback

Validate before calling

import fs from 'node:fs';
const candidates = ['src/mastra/index.ts', 'index.ts'];
if (!candidates.some(f => fs.existsSync(f))) {
  throw new Error(`No Mastra entry file found; expected one of: ${candidates.join(', ')}`);
}

Try / catch

try {
  await runCli(['dev']);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Missing required file')) {
    console.error('Run from the project root and ensure the Mastra entry file exists (e.g. src/mastra/index.ts).');
    process.exitCode = 1;
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

Related errors

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