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

Run the exact installCommand manually in the target path to reproduce and fix the failure

mastra-ai/mastra · error · MastraError

FAIL_CUSTOM_INSTALL_COMMAND

FAIL_CUSTOM_INSTALL_COMMAND

Error message

FAIL_CUSTOM_INSTALL_COMMAND

What it means

runInstallCommand executes a user-supplied install command via `sh -c <installCommand>` in the given path. If the command exits non-zero, a MastraError with id FAIL_CUSTOM_INSTALL_COMMAND (category USER, domain DEPLOYER) is thrown wrapping the execa error. It lets deployers override the default dependency-install step.

Source

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

  const args = ['install', '--legacy-peer-deps=false', '--force'];
  const { success, error } = await runWithExeca({ cmd: pm, args, cwd: path });
  if (!success) {
    throw new MastraError(
      {
        id: 'FAIL_INSTALL_DEPS',
        category: 'USER',
        domain: 'DEPLOYER',
      },
      error,
    );
  }
}

export async function runInstallCommand({ path, installCommand }: { path: string; installCommand: string }) {
  logger.info('Running install command', { command: installCommand, path });
  const { success, error } = await runWithExeca({ cmd: 'sh', args: ['-c', installCommand], cwd: path });
  if (!success) {
    throw new MastraError(
      {
        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,
  });

View on GitHub (pinned to 75dd419e61)

Solutions

Run the exact installCommand manually in the target path to reproduce and fix the failure
Ensure required binaries exist in the deploy environment image
Use absolute paths or set cwd explicitly in the command
Log/print the wrapped execa error detail to see the shell's stderr

Example fix

// before
await runInstallCommand({ path: outDir, installCommand: 'pnpm i --frozen-lockfile' }); // pnpm missing in image
// after
await runInstallCommand({ path: outDir, installCommand: 'npm ci' }); // npm guaranteed present

Defensive patterns

Strategy: try-catch

Validate before calling

sh -n -c "$INSTALL_COMMAND" && echo 'syntax ok'
command -v $(echo "$INSTALL_COMMAND" | awk '{print $1}') >/dev/null || echo 'binary missing'

Try / catch

try {
  await runInstallCommand({ path, installCommand });
} catch (err) {
  if (err instanceof MastraError && err.id === 'FAIL_CUSTOM_INSTALL_COMMAND') {
    console.error('Custom command failed:', err.cause); // stderr of sh -c
  } else throw err;
}

Prevention

Test the exact install command in a container matching the deploy image
Keep custom commands simple; prefer package scripts over inline shell chains
Reference binaries by absolute path when PATH may differ
Set -e style chaining deliberately and check each step

When it happens

Trigger: Calling runInstallCommand with an installCommand that fails — bad syntax, missing binary, or a real install error in the target directory.

Common situations: Custom command assumes a shell or binary not present in the deploy image; wrong cwd for the command; script exits non-zero due to env differences (CI vs local); typos in the custom install command.

Related errors

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