mastra-ai/mastra · error · MastraError

FAIL_BUILD_SCRIPT

FAIL_BUILD_SCRIPT

Error message

FAIL_BUILD_SCRIPT

What it means

runScript runs a package.json script via the package manager (`npm run <script>` for npm, `<pm> <script>` otherwise) in the given path. Non-zero exit throws a MastraError with id FAIL_BUILD_SCRIPT (category USER, domain DEPLOYER) wrapping the execa error. This is how cloud deploy executes build steps defined in your package.

Source

Thrown at deployers/cloud/src/utils/deps.ts:134

        id: 'FAIL_CUSTOM_INSTALL_COMMAND',
        category: 'USER',
        domain: 'DEPLOYER',
      },
      error,
    );
  }
}

export async function runScript({ scriptName, path, args }: { scriptName: string; path: string; args?: string[] }) {
  const pm = detectPm({ path });
  logger.info('Running script', { script: scriptName, pm });
  const { success, error } = await runWithExeca({
    cmd: pm,
    args: pm === 'npm' ? ['run', scriptName, ...(args ?? [])] : [scriptName, ...(args ?? [])],
    cwd: path,
  });
  if (!success) {
    throw new MastraError(
      {
        id: 'FAIL_BUILD_SCRIPT',
        category: 'USER',
        domain: 'DEPLOYER',
      },
      error,
    );
  }
}

export async function runBuildCommand({ command, path }: { command: string; path: string }) {
  logger.info('Running build command', { command });
  const { success, error } = await runWithExeca({ cmd: 'sh', args: ['-c', command], cwd: path });
  if (!success) {
    throw new MastraError(
      {
        id: 'FAIL_BUILD_COMMAND',
        category: 'USER',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the wrapped execa stderr to see the script's failure output and fix the underlying build error
2. Verify the script exists in the output directory's package.json
3. Increase Node memory for the build (NODE_OPTIONS=--max-old-space-size=4096)
4. Remove local-only steps (tests, lint) from the build script used in deploy

Example fix

// before
{ "scripts": { "build": "tsc && vitest run" } } // tests fail in deploy env
// after
{ "scripts": { "build": "tsc", "test": "vitest run" } }

node -e "const p=require('./package.json'); process.exit(p.scripts?.[scriptName] ? 0 : 1)" || echo 'script missing'

try {
  await runScript({ path, pm, scriptName, args });
} catch (err) {
  if (err instanceof MastraError && err.id === 'FAIL_BUILD_SCRIPT') {
    console.error('Script failed:', err.cause); // script stdout/stderr here
  } else throw err;
}

When it happens

Trigger: Calling runScript (e.g. to run a `build` script) during deploy when the script exits with an error — compilation failure, missing script name, or failing test/lint step chained into it.

Common situations: TypeScript/build errors in the bundled output; script name not present in the output directory's package.json; memory exhaustion (OOM) on large builds in constrained CI; scripts that depend on dev-only env vars.

Related errors

• FAIL_BUILD_COMMAND
• NODE_FAIL_INSTALL_SPECIFIED_VERSION
• FAIL_INSTALL_DEPS
• FAIL_CUSTOM_INSTALL_COMMAND
• 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/ec534af05467c67e. Report an issue: GitHub.