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

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.

Source

Thrown at packages/deployer/src/services/fs.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(', '));
  }

  /**
   * Returns every existing file from the provided array in the same order.
   * Callers supply files from the lowest to highest precedence so later dotenv
   * files override earlier values when the bundler loads them.
   */
  public getExistingFiles(files: string[]): string[] {
    return files.filter(file => fs.existsSync(file));
  }

  /**
   * Returns the first existing file from the provided array, or undefined if none exist
   * @param files array of file paths to check
   * @returns the first existing file path or undefined
   */
  public getFirstExistingFileOrUndefined(files: string[]): string | undefined {
    for (const f of files) {

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before (project root, no entry file)
src/index.ts  // Mastra instance lives here, deployer can't find it

// after
mkdir -p src/mastra
cat > src/mastra/index.ts <<'EOF'
import { Mastra } from '@mastra/core/mastra';
export const mastra = new Mastra({});
EOF

Defensive patterns

Strategy: validation

Validate before calling

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

Type guard

function hasMastraEntry(dir: string): boolean {
  return ['src/mastra/index.ts', 'mastra/index.ts', 'index.ts'].some(f => fs.existsSync(path.join(dir, f)));
}

Try / catch

try {
  const entry = getMastraEntryFile(dir);
} catch (err) {
  if ((err as Error).message.startsWith('Missing required file')) {
    console.error('No Mastra entry found. Run `mastra init` or check --dir.');
    process.exit(1);
  }
  throw err;
}

Prevention

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

When it happens

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

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

Related errors

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