{"record":{"id":"74057d3aad277c1d","repo":"mastra-ai/mastra","slug":"mastra-entry-file-not-found","errorCode":"MASTRA_ENTRY_FILE_NOT_FOUND","errorMessage":"MASTRA_ENTRY_FILE_NOT_FOUND","messagePattern":"MASTRA_ENTRY_FILE_NOT_FOUND","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"deployers/cloud/src/utils/file.ts","lineNumber":15,"sourceCode":"import { join } from 'node:path';\nimport { MastraError } from '@mastra/core/error';\nimport { FileService } from '@mastra/deployer';\n\nimport { MASTRA_DIRECTORY } from './constants.js';\n\nexport function getMastraEntryFile(mastraDir: string) {\n  try {\n    const fileService = new FileService();\n    return fileService.getFirstExistingFile([\n      join(mastraDir, MASTRA_DIRECTORY, 'index.ts'),\n      join(mastraDir, MASTRA_DIRECTORY, 'index.js'),\n    ]);\n  } catch (error) {\n    throw new MastraError(\n      {\n        id: 'MASTRA_ENTRY_FILE_NOT_FOUND',\n        category: 'USER',\n        domain: 'DEPLOYER',\n      },\n      error,\n    );\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":25,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloud/src/utils/file.ts#L1-L25","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run `mastra build` before deploying so .mastra/index.ts is generated","Verify your mastraDir/outputDir configuration points to the directory containing .mastra/index.ts","Check CI didn't clean the .mastra directory between build and deploy","Run the deployer from the project root where .mastra lives"],"exampleFix":"// before\n$ mastra deploy cloud # .mastra/ missing\n// after\n$ mastra build && mastra deploy cloud # generates .mastra/index.ts first","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nif (!existsSync(join(mastraDir, '.mastra', 'index.ts')) && !existsSync(join(mastraDir, '.mastra', 'index.js'))) {\n  throw new Error('Run `mastra build` first: .mastra/index.(ts|js) missing');\n}","typeGuard":null,"tryCatchPattern":"try {\n  const entry = await getMastraEntryFile(mastraDir);\n} catch (err) {\n  if (err instanceof MastraError && err.id === 'MASTRA_ENTRY_FILE_NOT_FOUND') {\n    console.error('Entry file missing — run `mastra build` and check outputDir');\n  } else throw err;\n}","preventionTips":["Always run `mastra build` before deploy commands","Exclude .mastra from CI clean steps between build and deploy","Verify mastraDir/outputDir configuration matches the deployer's cwd","Add a predeploy check that .mastra/index.ts exists"],"tags":["deployment","entry-file","filesystem","config"],"backgroundTag":"entry-file-not-found","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}