What causes "Output directory ${outputPath} does not exist" in mastra-ai/mastra?

Run `mastra build` first to generate the `.mastra/output` directory, then run `mastra start`.

Output directory ${outputPath} does not exist

Error message

Output directory ${outputPath} does not exist

What it means

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.

Source

Thrown at packages/cli/src/commands/start/start.ts:39

// Append a stderr chunk while keeping only the last `max` characters, so the
// retained buffer can never grow without bound.
export function boundStderr(buffer: string, chunk: string, max: number = MAX_STDERR_BUFFER): string {
  return (buffer + chunk).slice(-max);
}

export async function start(options: StartOptions = {}) {
  // Load environment variables from .env files
  if (!shouldSkipDotenvLoading()) {
    config({ path: [options.env || '.env.production', '.env'], quiet: true });
  }
  const outputDir = options.dir || '.mastra/output';

  try {
    // Check if the output directory exist
    const outputPath = join(process.cwd(), outputDir);
    if (!fs.existsSync(outputPath)) {
      throw new Error(`Output directory ${outputPath} does not exist`);
    }

    const commands = [];

    if (options.customArgs) {
      commands.push(...options.customArgs);
    }

    commands.push('index.mjs');

    // Start the server using node
    const server = spawn(process.execPath, commands, {
      cwd: outputPath,
      stdio: ['inherit', 'inherit', 'pipe'],
      env: {
        ...process.env,
        NODE_ENV: 'production',
        MASTRA_TELEMETRY_COMMAND: 'start',

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
mastra start
// after
mastra build && mastra start

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';
import { join } from 'node:path';
const dir = options.dir ?? '.mastra/output';
if (!fs.existsSync(join(process.cwd(), dir))) {
  throw new Error(`Run 'mastra build' first; ${dir} not found in ${process.cwd()}`);
}

Try / catch

try {
  await start(options);
} catch (err) {
  if ((err as Error).message.includes('Output directory') && err.message.includes('does not exist')) {
    console.error('Run `mastra build` first, or pass --dir pointing at your build output.');
    process.exit(1);
  }
  throw err;
}

Prevention

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.

When it happens

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

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

Related errors

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