mastra-ai/mastra · error

No index.mjs found in

Error message

No index.mjs found in "${dir}" — did the build succeed?

What it means

deployToSandbox verifies that the build output directory contains index.mjs (the Mastra server bundle entry) before doing anything else. If it's missing, the build output is assumed to be incomplete or absent, so the deploy aborts early.

Solutions

1. Run the build (`mastra build` or equivalent) before deploying
2. Check that dir/index.mjs exists locally before deploying (ls <dir>)
3. If using a custom build, configure output filename to index.mjs or point dir at the real output directory
4. Fix any silent build failures reported earlier in CI logs

Example fix

// before
npx mastra deploy --dir ./output   # never built
// after
npx mastra build && npx mastra deploy --dir ./output

import { existsSync } from 'node:fs';
import { join } from 'node:path';
if (!existsSync(join(dir, 'index.mjs'))) {
  throw new Error(`build output missing: run the build before deploying to ${dir}`);
}

When it happens

Trigger: Calling deployToSandbox with a `dir` that was never built, points at the wrong directory, or where the build emitted a different entry filename.

Common situations: Forgetting to run the build before deploying; running the deployer from the wrong working directory so `dir` resolves elsewhere; custom bundler output naming (e.g. index.js instead of index.mjs); a failed build that still exited 0.

Related errors

• FAIL_BUILD_COMMAND
• FAIL_BUILD_SCRIPT
• Failed to copy studio assets from
• command failed (exit )
• Mastra server did not become healthy at

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

Appendix: source

Thrown at deployers/sandbox/src/engine.ts:60

 * contract (`executeCommand` + `networking`, with `writeFiles` / `processes`
 * as fast paths).
 */
export async function deployToSandbox(options: DeployToSandboxOptions): Promise<SandboxDeployment> {
  const {
    sandbox,
    dir,
    port = DEFAULT_PORT,
    env = {},
    studio = false,
    healthCheckPath = '/api',
    healthCheckTimeoutMs = 60_000,
    healthCheckIntervalMs = 1_000,
    installCommand = 'npm install --omit=dev',
    logger = noopLogger,
  } = options;

  if (!existsSync(join(dir, 'index.mjs'))) {
    throw new Error(`No index.mjs found in "${dir}" — did the build succeed?`);
  }

  // 1. Start (providers handle create-or-resume by identity, e.g. sandbox name).
  logger.info(`Starting ${sandbox.provider} sandbox...`);
  await sandbox.start?.();

  if (!supportsNetworking(sandbox)) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support networking (public port URLs), ` +
        `which is required for sandbox deploys.`,
    );
  }
  if (!sandbox.executeCommand) {
    throw new Error(
      `Sandbox provider "${sandbox.provider}" does not support executeCommand, which is required for sandbox deploys.`,
    );
  }

View on GitHub (pinned to 75dd419e61)