{"record":{"id":"81fbd97546eda1b1","repo":"mastra-ai/mastra","slug":"output-directory-outputpath-does-not-exist","errorCode":null,"errorMessage":"Output directory ${outputPath} does not exist","messagePattern":"Output directory (.+?) does not exist","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/cli/src/commands/start/start.ts","lineNumber":39,"sourceCode":"\n// Append a stderr chunk while keeping only the last `max` characters, so the\n// retained buffer can never grow without bound.\nexport function boundStderr(buffer: string, chunk: string, max: number = MAX_STDERR_BUFFER): string {\n  return (buffer + chunk).slice(-max);\n}\n\nexport async function start(options: StartOptions = {}) {\n  // Load environment variables from .env files\n  if (!shouldSkipDotenvLoading()) {\n    config({ path: [options.env || '.env.production', '.env'], quiet: true });\n  }\n  const outputDir = options.dir || '.mastra/output';\n\n  try {\n    // Check if the output directory exist\n    const outputPath = join(process.cwd(), outputDir);\n    if (!fs.existsSync(outputPath)) {\n      throw new Error(`Output directory ${outputPath} does not exist`);\n    }\n\n    const commands = [];\n\n    if (options.customArgs) {\n      commands.push(...options.customArgs);\n    }\n\n    commands.push('index.mjs');\n\n    // Start the server using node\n    const server = spawn(process.execPath, commands, {\n      cwd: outputPath,\n      stdio: ['inherit', 'inherit', 'pipe'],\n      env: {\n        ...process.env,\n        NODE_ENV: 'production',\n        MASTRA_TELEMETRY_COMMAND: 'start',","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/cli/src/commands/start/start.ts#L21-L57","documentation":"Thrown by the `mastra start` command when the build output directory (default `.mastra/output`, or the path given via `--dir`) does not exist under the current working directory. `mastra start` serves an already-built project, so the compiled output must exist first. The check is an fs.existsSync guard before spawning the server process.","triggerScenarios":"Running `mastra start` (or `mastra start --dir <path>`) before ever running `mastra build`, running it in the wrong working directory, or pointing `--dir` at a non-existent or misspelled path.","commonSituations":"Fresh clone where the developer runs `start` instead of `build` first; CI pipelines skipping the build step; renaming or customizing the output directory without passing `--dir`; running from a subdirectory of the project.","solutions":["Run `mastra build` first to generate the `.mastra/output` directory, then run `mastra start`.","If your output is elsewhere, pass the correct path: `mastra start --dir path/to/output`.","Run the command from the project root (the directory containing `.mastra/output`).","Verify the directory exists: `ls .mastra/output` in your current working directory."],"exampleFix":"// before\nmastra start\n// after\nmastra build && mastra start","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nimport { join } from 'node:path';\nconst dir = options.dir ?? '.mastra/output';\nif (!fs.existsSync(join(process.cwd(), dir))) {\n  throw new Error(`Run 'mastra build' first; ${dir} not found in ${process.cwd()}`);\n}","typeGuard":null,"tryCatchPattern":"try {\n  await start(options);\n} catch (err) {\n  if ((err as Error).message.includes('Output directory') && err.message.includes('does not exist')) {\n    console.error('Run `mastra build` first, or pass --dir pointing at your build output.');\n    process.exit(1);\n  }\n  throw err;\n}","preventionTips":["Always run `mastra build` before `mastra start` (chain them in scripts: \"start\": \"mastra build && mastra start\").","Run CLI commands from the project root.","If you use a custom output dir, keep the --dir flag in your scripts.","Add the output dir existence check to CI before the start step."],"tags":["cli","filesystem","missing-directory","build"],"backgroundTag":"missing-build-output","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}