mastra-ai/mastra · error · SetupCommandError

${label} command failed (exit ${result.exitCode}): ${detail}

Error message

${label} command failed (exit ${result.exitCode}): ${detail}

What it means

A setup or teardown command run inside the sandbox exited non-zero; the code captures the last 1800 chars of stderr (or stdout) and throws SetupCommandError with code 'setup-failed' or 'teardown-failed'. The library uses this to surface exactly which phase (setup vs teardown) and which command failed during project build preparation.

Source

Thrown at mastracode/factory/src/integrations/github/sandbox.ts:835

 *
 * @param sandbox  live sandbox containing the checkout
 * @param workdir  the server-resolved session workdir the command runs in
 * @param command  the org-configured setup shell command
 */
async function runLifecycleCommand(
  sandbox: ExecutableSandbox,
  workdir: string,
  command: string,
  options: { phase: 'setup' | 'teardown'; timeoutMs?: number },
): Promise<void> {
  const result = await sh(sandbox, `cd ${shellQuote(workdir)} && { ${command}\n}`, {
    phase: `${options.phase} command`,
    ...(options.timeoutMs !== undefined ? { timeoutMs: options.timeoutMs } : {}),
  });
  if (result.exitCode !== 0) {
    const detail = (result.stderr.trim() || result.stdout.trim()).slice(-1800);
    const label = options.phase === 'setup' ? 'Setup' : 'Teardown';
    throw new SetupCommandError(
      `${label} command failed (exit ${result.exitCode}): ${detail}`,
      options.phase === 'setup' ? 'setup-failed' : 'teardown-failed',
    );
  }
}

export async function runSetupCommand(
  sandbox: ExecutableSandbox,
  workdir: string,
  command: string,
): Promise<void> {
  return runLifecycleCommand(sandbox, workdir, command, { phase: 'setup' });
}

/**
 * Run the repository's best-effort teardown command from the materialized
 * session workdir. Callers own lifecycle policy: this helper reports failures
 * so the retirement coordinator can log them while still continuing with

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read the exit code and trailing stderr in the message to identify the failing command
2. Re-run locally to reproduce (e.g. run the same install/build command in a matching container)
3. Ensure the sandbox template includes all required tools for the phase
4. Fix the underlying build/dependency error the output points to, then retry

Example fix

// before
// Setup command failed (exit 1): pnpm: not found
// after (sandbox template Dockerfile)
RUN corepack enable && corepack prepare pnpm@latest --activate

const which = await sh(sandbox, 'sh -c "command -v pnpm npm node git"');
if (which.exitCode !== 0) throw new Error('required tools missing in sandbox');

try {
  await runSetup(sandbox, options);
} catch (e) {
  if (e instanceof SetupCommandError && e.code === 'setup-failed') {
    // e.message ends with the last 1800 chars of the command output; read it to find the failing step
  }
  throw e;
}

When it happens

Trigger: Any command in the setup or teardown phase returns a non-zero exit code — package install failures (npm/pnpm install), build script errors, or missing tools in the sandbox template.

Common situations: Dependency install fails due to registry auth or network; build fails on type errors; tool required by the phase (e.g. pnpm) not installed in the sandbox image.

Related errors

• FAIL_BUILD_COMMAND
• No index.mjs found in "${dir}" — did the build succeed?
• Invalid environment variable name: "${key}"
• Resource-limit preflight command failed.
• Unable to read worker ${stream}.

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