.mastra/output/index.mjs not found — did the build succeed?

Error message

.mastra/output/index.mjs not found — did the build succeed?

What it means

After (optionally) building, runServerDeploy verifies the build entrypoint .mastra/output/index.mjs exists via fs access. If the file is absent it throws — the CLI refuses to package and upload a deploy that has no build artifact, since the platform build would have nothing to run.

Source

Thrown at packages/cli/src/commands/server/deploy.ts:482

    }
    p.log.step('Skipping build (--skip-build)');
  } else if (staleness.isStale) {
    // Build is stale or doesn't exist — rebuild
    if (staleness.reason === 'hash-mismatch') {
      p.log.step('Source files changed, rebuilding...');
    }
    await runBuild(targetDir, { debug: opts.debug });
  } else {
    // Build is up-to-date — skip rebuild
    p.log.step('Build is up-to-date, skipping rebuild');
  }

  // Verify build output exists
  const outputEntry = join(targetDir, '.mastra', 'output', 'index.mjs');
  try {
    await access(outputEntry);
  } catch {
    throw new Error('.mastra/output/index.mjs not found — did the build succeed?');
  }

  // If the user didn't pass --env-file and no ambient .env* file exists,
  // skip the local env-var upload entirely and let the platform use the
  // env vars stored on the project. The server-side deploy handler merges
  // request envVars over the stored vars, so an empty (absent) envVars
  // payload cleanly falls back to what's already stored.
  let envVars: Record<string, string> = {};
  const hasEnvFile = opts.envFile ? true : (await getDeployEnvFiles(targetDir)).length > 0;
  if (hasEnvFile) {
    envVars = await readEnvVars(targetDir, { autoAccept, envFile: opts.envFile });
  }
  const envCount = Object.keys(envVars).length;
  if (envCount > 0) {
    p.log.step(`Found ${envCount} env var(s)`);
  } else if (hasEnvFile) {
    p.log.step('No env vars found in selected env file');
  } else {

View on GitHub (pinned to 75dd419e61)

Solutions

Run `mastra build` in the deploy directory and check it completes without errors, then confirm .mastra/output/index.mjs exists
Fix the underlying build failure (inspect `mastra build` output for TS/import errors)
Remove --skipBuild, or run a build before deploying with --skipBuild
If output path is customized, ensure the entry lands at .mastra/output/index.mjs or revert the custom output config
Run the deploy from the correct package directory in monorepos

Example fix

// before (package.json script)
"deploy": "mastra build || true && mastra server deploy --skipBuild"
// after
"deploy": "mastra build && mastra server deploy"

Defensive patterns

Strategy: validation

Validate before calling

import { access } from 'node:fs/promises';
// Run before deploying
try {
  await access('.mastra/output/index.mjs');
} catch {
  throw new Error('Build output missing — run `mastra build` first.');
}

Type guard

function isStatFile(stat: { isFile(): boolean } | undefined): boolean {
  return Boolean(stat?.isFile());
}

Try / catch

try {
  await deploy();
} catch (err) {
  if (err instanceof Error && err.message.includes('not found — did the build succeed?')) {
    console.error('Run `mastra build` and confirm .mastra/output/index.mjs exists.');
    process.exitCode = 1;
  } else throw err;
}

Prevention

Chain build and deploy with && so a failed build blocks deploy
Never use `|| true` around build steps in CI
Verify .mastra/output/index.mjs exists after customizing build output paths
Run deploys from the package directory that owns the .mastra output

When it happens

Trigger: Deploy ran with a build that failed or produced no output; build wrote output to a different directory; `mastra build` was never run in this project; --skipBuild was passed in a directory with no prior successful build; a custom build config changed the output path away from .mastra/output.

Common situations: Build step failed earlier (TS errors, missing deps) but the deploy script continued due to `|| true` or ignore-errors CI settings; wrong working directory (deploying from repo root of a monorepo where build outputs live in packages/*); mastraConfig output customized.

Related errors

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