What causes "FAIL_BUILD_COMMAND" in mastra-ai/mastra?

Re-run the exact command in the target path locally to see the failure

mastra-ai/mastra · error · MastraError

FAIL_BUILD_COMMAND

FAIL_BUILD_COMMAND

Error message

FAIL_BUILD_COMMAND

What it means

runBuildCommand executes an arbitrary build command via `sh -c <command>` in the given path and throws a MastraError with id FAIL_BUILD_COMMAND (category USER, domain DEPLOYER) if it exits non-zero, wrapping the execa error. It is the free-form counterpart to runScript for custom build pipelines in cloud deploys.

Source

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

    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',
        domain: 'DEPLOYER',
      },
      error,
    );
  }
}

View on GitHub (pinned to 75dd419e61)

Solutions

Re-run the exact command in the target path locally to see the failure
Check the wrapped execa error's stdout/stderr for root cause
Ensure all toolchain binaries are installed in the deploy image
Simplify quoting: put complex logic in a script file and invoke it

Example fix

// before
await runBuildCommand({ command: 'export NODE_ENV=production && nx build api', path }); // nx not in image
// after
await runBuildCommand({ command: 'npm run build', path }); // uses local package script

Defensive patterns

Strategy: try-catch

Validate before calling

sh -n -c "$BUILD_COMMAND" || echo 'invalid shell syntax'
command -v ${BUILD_COMMAND%% *} >/dev/null || echo 'first binary missing'

Try / catch

try {
  await runBuildCommand({ command, path });
} catch (err) {
  if (err instanceof MastraError && err.id === 'FAIL_BUILD_COMMAND') {
    console.error('Build command failed:', err.cause); // includes stdout/stderr
  } else throw err;
}

Prevention

Verify all toolchain binaries exist in the deploy image
Move complex logic into a script file to avoid quoting bugs
Export needed env vars explicitly; non-interactive sh does not source profiles
Test the identical command in CI before deploying

When it happens

Trigger: Calling runBuildCommand with a command that fails in the deploy environment — unknown binary, failing compilation, or a chained command returning non-zero.

Common situations: Custom build command depends on tools absent from the deploy image; shell quoting issues in complex commands; environment variables not exported in non-interactive `sh -c`; genuinely failing build (type errors, missing assets).

Related errors

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