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

Run the same install command locally in the output directory and fix the reported dependency conflict

mastra-ai/mastra · error · MastraError

FAIL_INSTALL_DEPS

FAIL_INSTALL_DEPS

Error message

FAIL_INSTALL_DEPS

What it means

installDeps runs the detected package manager (`pm`) with `install --legacy-peer-deps=false --force` inside the build output directory. Non-zero exit throws a MastraError with id FAIL_INSTALL_DEPS (category USER, domain DEPLOYER) wrapping the underlying execa error. The special flags exist to pull peer deps for external packages and to override repo-level overrides such as pnpm's.

Source

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

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

export async function installDeps({ path, pm }: { path: string; pm?: string }) {
  pm = pm ?? detectPm({ path });
  logger.info('Installing dependencies', { pm, path });
  // --force is needed to install peer deps for external packages in the mastra output directory
  // --legacy-peer-deps=false is needed to override other overrides by the repo package manager such as pnpm. Pnpm would set it to true
  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',

View on GitHub (pinned to 75dd419e61)

Solutions

Run the same install command locally in the output directory and fix the reported dependency conflict
Configure registry auth (NPM_TOKEN/.npmrc) for private packages
Delete the lockfile or regenerate it for the target platform, then redeploy
Clear the package manager cache and retry

Example fix

// before
{ "dependencies": { "@acme/secret-sdk": "^1" } } // private, no auth in CI
// after
// .npmrc
// @acme:registry=https://npm.acme.dev/
// //npm.acme.dev/:_authToken=${NPM_TOKEN}

Defensive patterns

Strategy: try-catch

Validate before calling

// dry-run install in the output dir before deploying
cd <outputDir> && npm install --legacy-peer-deps=false --force --dry-run || echo 'fix deps first'

Try / catch

try {
  await installDependencies({ ... });
} catch (err) {
  if (err instanceof MastraError && err.id === 'FAIL_INSTALL_DEPS') {
    console.error('Install failed:', err.cause); // inspect peer-dep/registry errors
  } else throw err;
}

Prevention

Keep a valid lockfile and test `npm install` locally in the built output
Configure registry auth tokens (.npmrc) for private packages in CI
Avoid repo-level overrides (pnpm overrides) that leak into the output install
Rebuild native deps for the deploy target OS/architecture

When it happens

Trigger: Calling installDependencies (which invokes installDeps) during cloud deploy when `npm/pnpm/yarn install` fails in the output directory.

Common situations: Missing or conflicting peer dependencies even with --force; private registry packages without auth tokens; lockfile/platform mismatch (e.g. native modules for the wrong OS/arch); corrupted package cache.

Related errors

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