{"record":{"id":"0f712c8f7b36fdcd","repo":"mastra-ai/mastra","slug":"fail-install-deps","errorCode":"FAIL_INSTALL_DEPS","errorMessage":"FAIL_INSTALL_DEPS","messagePattern":"FAIL_INSTALL_DEPS","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"deployers/cloud/src/utils/deps.ts","lineNumber":99,"sourceCode":"          id: 'NODE_FAIL_INSTALL_SPECIFIED_VERSION',\n          category: 'USER',\n          domain: 'DEPLOYER',\n        },\n        error,\n      );\n    }\n  }\n}\n\nexport async function installDeps({ path, pm }: { path: string; pm?: string }) {\n  pm = pm ?? detectPm({ path });\n  logger.info('Installing dependencies', { pm, path });\n  // --force is needed to install peer deps for external packages in the mastra output directory\n  // --legacy-peer-deps=false is needed to override other overrides by the repo package manager such as pnpm. Pnpm would set it to true\n  const args = ['install', '--legacy-peer-deps=false', '--force'];\n  const { success, error } = await runWithExeca({ cmd: pm, args, cwd: path });\n  if (!success) {\n    throw new MastraError(\n      {\n        id: 'FAIL_INSTALL_DEPS',\n        category: 'USER',\n        domain: 'DEPLOYER',\n      },\n      error,\n    );\n  }\n}\n\nexport async function runInstallCommand({ path, installCommand }: { path: string; installCommand: string }) {\n  logger.info('Running install command', { command: installCommand, path });\n  const { success, error } = await runWithExeca({ cmd: 'sh', args: ['-c', installCommand], cwd: path });\n  if (!success) {\n    throw new MastraError(\n      {\n        id: 'FAIL_CUSTOM_INSTALL_COMMAND',\n        category: 'USER',","sourceCodeStart":81,"sourceCodeEnd":117,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloud/src/utils/deps.ts#L81-L117","documentation":"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.","triggerScenarios":"Calling installDependencies (which invokes installDeps) during cloud deploy when `npm/pnpm/yarn install` fails in the output directory.","commonSituations":"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.","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"],"exampleFix":"// before\n{ \"dependencies\": { \"@acme/secret-sdk\": \"^1\" } } // private, no auth in CI\n// after\n// .npmrc\n// @acme:registry=https://npm.acme.dev/\n// //npm.acme.dev/:_authToken=${NPM_TOKEN}","handlingStrategy":"try-catch","validationCode":"// dry-run install in the output dir before deploying\ncd <outputDir> && npm install --legacy-peer-deps=false --force --dry-run || echo 'fix deps first'","typeGuard":null,"tryCatchPattern":"try {\n  await installDependencies({ ... });\n} catch (err) {\n  if (err instanceof MastraError && err.id === 'FAIL_INSTALL_DEPS') {\n    console.error('Install failed:', err.cause); // inspect peer-dep/registry errors\n  } else throw err;\n}","preventionTips":["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"],"tags":["install","deployment","dependencies","subprocess"],"backgroundTag":"dependency-install-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}