mastra-ai/mastra · error · MastraError

MASTRA_ENTRY_FILE_NOT_FOUND

MASTRA_ENTRY_FILE_NOT_FOUND

Error message

MASTRA_ENTRY_FILE_NOT_FOUND

What it means

getMastraEntryFile locates your Mastra entry point by looking for <mastraDir>/.mastra/index.ts or index.js via FileService. If neither exists (the lookup throws), it throws a MastraError with id MASTRA_ENTRY_FILE_NOT_FOUND (category USER, domain DEPLOYER) wrapping the original error. Deployers need this entry file to bundle your agent/workflow code.

Source

Thrown at deployers/cloud/src/utils/file.ts:15

import { join } from 'node:path';
import { MastraError } from '@mastra/core/error';
import { FileService } from '@mastra/deployer';

import { MASTRA_DIRECTORY } from './constants.js';

export function getMastraEntryFile(mastraDir: string) {
  try {
    const fileService = new FileService();
    return fileService.getFirstExistingFile([
      join(mastraDir, MASTRA_DIRECTORY, 'index.ts'),
      join(mastraDir, MASTRA_DIRECTORY, 'index.js'),
    ]);
  } catch (error) {
    throw new MastraError(
      {
        id: 'MASTRA_ENTRY_FILE_NOT_FOUND',
        category: 'USER',
        domain: 'DEPLOYER',
      },
      error,
    );
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Run `mastra build` before deploying so .mastra/index.ts is generated
2. Verify your mastraDir/outputDir configuration points to the directory containing .mastra/index.ts
3. Check CI didn't clean the .mastra directory between build and deploy
4. Run the deployer from the project root where .mastra lives

Example fix

// before
$ mastra deploy cloud # .mastra/ missing
// after
$ mastra build && mastra deploy cloud # generates .mastra/index.ts first

import { existsSync } from 'node:fs';
import { join } from 'node:path';
if (!existsSync(join(mastraDir, '.mastra', 'index.ts')) && !existsSync(join(mastraDir, '.mastra', 'index.js'))) {
  throw new Error('Run `mastra build` first: .mastra/index.(ts|js) missing');
}

try {
  const entry = await getMastraEntryFile(mastraDir);
} catch (err) {
  if (err instanceof MastraError && err.id === 'MASTRA_ENTRY_FILE_NOT_FOUND') {
    console.error('Entry file missing — run `mastra build` and check outputDir');
  } else throw err;
}

When it happens

Trigger: Calling getMastraEntryFile (via mastraEntryFile) for a directory where <dir>/.mastra/index.ts or index.js does not exist — typically because the build step was skipped or output went elsewhere.

Common situations: Deploying before running `mastra build`; custom outputDir/mastraDir configuration pointing at the wrong path; .mastra directory deleted by CI cleaning; running the deployer from the wrong working directory.

Related errors

• Failed to copy studio assets from "${studioSource}" to "${st
• Presets file not found: ${absolutePath}
• skillPath does not exist on the server filesystem: ${resolve
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio

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