{"record":{"id":"316b90e09d98230c","repo":"mastra-ai/mastra","slug":"node-fail-install-specified-version","errorCode":"NODE_FAIL_INSTALL_SPECIFIED_VERSION","errorMessage":"NODE_FAIL_INSTALL_SPECIFIED_VERSION","messagePattern":"NODE_FAIL_INSTALL_SPECIFIED_VERSION","errorType":"error_code","errorClass":"MastraError","httpStatus":null,"severity":"error","filePath":"deployers/cloud/src/utils/deps.ts","lineNumber":79,"sourceCode":"    // File does not exist\n  }\n\n  try {\n    fs.accessSync(join(path, '.node-version'));\n    nodeVersionExists = true;\n  } catch {\n    // File does not exist\n  }\n\n  if (nvmrcExists || nodeVersionExists) {\n    logger.info('Node version file found, installing specified Node.js version...');\n    const { success, error } = await runWithExeca({\n      cmd: 'n',\n      args: ['auto'],\n      cwd: path,\n    });\n    if (!success) {\n      throw new MastraError(\n        {\n          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 });","sourceCodeStart":61,"sourceCodeEnd":97,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/deployers/cloud/src/utils/deps.ts#L61-L97","documentation":"installNodeVersion in deployers/cloud runs `n auto` in the bundle directory to provision the matching Node version for cloud deployment. When that subprocess exits non-zero, a MastraError with id NODE_FAIL_INSTALL_SPECIFIED_VERSION (category USER, domain DEPLOYER) is thrown, wrapping the execa error.","triggerScenarios":"Calling installNodeVersion during a cloud deploy when the `n` node version manager fails to resolve/install the target version.","commonSituations":"`n` not installed or not on PATH; no write permission to /usr/local (n's default prefix); restricted network blocking nodejs.org downloads; unsupported/typos Node version resolution with 'auto'.","solutions":["Install the `n` version manager and ensure it is on PATH","Run with permission to write n's prefix (e.g. N_PREFIX with chown, or sudo-cached install)","Verify network access to nodejs.org from the deploy environment","Pre-install the required Node version yourself and retry the deploy"],"exampleFix":"// before\n$ mastra deploy cloud # fails: n not found\n// after\n$ npm i -g n && sudo mkdir -p /usr/local/n && sudo chown -R $(whoami) /usr/local/n\n$ mastra deploy cloud","handlingStrategy":"try-catch","validationCode":"which n || { echo 'n version manager missing'; exit 1; }\nnode -e \"fs.accessSync(process.env.N_PREFIX || '/usr/local/n', fs.constants.W_OK)\" || echo 'n prefix not writable'","typeGuard":null,"tryCatchPattern":"try {\n  await installNodeVersion({ path, version });\n} catch (err) {\n  if (err instanceof MastraError && err.id === 'NODE_FAIL_INSTALL_SPECIFIED_VERSION') {\n    console.error('n failed:', err.cause); // check PATH, N_PREFIX perms, network\n  } else throw err;\n}","preventionTips":["Pre-install `n` and set a writable N_PREFIX in deploy images","Verify network egress to nodejs.org in CI/deploy environments","Pre-provision the exact Node version to avoid `n auto` at deploy time","Run deploys with a user that owns n's install prefix"],"tags":["node","install","deployment","subprocess"],"backgroundTag":"node-version-install-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}