mastra-ai/mastra · error

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

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.

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)

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_SCRIPT
• FAIL_BUILD_COMMAND
• Sandbox provider "${sandbox.provider}" did not expose a publ
• Woke sandbox but the Mastra server did not become healthy at
• Failed to copy studio assets from "${studioSource}" to "${st

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