{"record":{"id":"943aed2fec6b60af","repo":"yarnpkg/yarn","slug":"nodegypautoinstallfailed","errorCode":null,"errorMessage":"nodeGypAutoInstallFailed","messagePattern":"nodeGypAutoInstallFailed","errorType":"exception","errorClass":"MessageError","httpStatus":null,"severity":"error","filePath":"src/util/execute-lifecycle-script.js","lineNumber":322,"sourceCode":"  return checkGypPromise;\n}\n\nasync function _checkForGyp(config: Config, paths: Array<string>): Promise<void> {\n  const {reporter} = config;\n\n  // Check every directory in the PATH\n  const allChecks = await Promise.all(paths.map(dir => fs.exists(path.join(dir, 'node-gyp'))));\n  if (allChecks.some(Boolean)) {\n    // node-gyp is available somewhere\n    return;\n  }\n\n  reporter.info(reporter.lang('packageRequiresNodeGyp'));\n\n  try {\n    await globalRun(config, reporter, {}, ['add', 'node-gyp']);\n  } catch (e) {\n    throw new MessageError(reporter.lang('nodeGypAutoInstallFailed', e.message));\n  }\n}\n\nexport async function execFromManifest(config: Config, commandName: string, cwd: string): Promise<void> {\n  const pkg = await config.maybeReadManifest(cwd);\n  if (!pkg || !pkg.scripts) {\n    return;\n  }\n\n  const cmd: ?string = pkg.scripts[commandName];\n  if (cmd) {\n    await execCommand({stage: commandName, config, cmd, cwd, isInteractive: true});\n  }\n}\n\nexport async function execCommand({\n  stage,\n  config,","sourceCodeStart":304,"sourceCodeEnd":340,"githubUrl":"https://github.com/yarnpkg/yarn/blob/c2dda503f3759b5be5f0e24ecd9cf5c97a540147/src/util/execute-lifecycle-script.js#L304-L340","documentation":"When node-gyp is not found anywhere on PATH, Yarn attempts to auto-install it globally via globalRun(['add','node-gyp']). If that global add fails, nodeGypAutoInstallFailed wraps the underlying error message. Yarn needs node-gyp to compile native addon install scripts.","triggerScenarios":"A package's lifecycle script requires node-gyp; PATH has no node-gyp binary; the global add fails due to network, proxy, or permissions. nodeGypAutoInstallFailed wraps e.message.","commonSituations":"Restricted CI environments; corporate proxies blocking the install; permission errors on the global node_modules directory; running offline.","solutions":["Install node-gyp globally beforehand: npm install -g node-gyp","Ensure native build tools (Python, C++ compiler, make) are installed","Check network/proxy settings allow registry access for the global install","Run the install with appropriate write permissions for global node_modules"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"import * as path from 'path';\nasync function isNodeGypAvailable(paths: string[]): Promise<boolean> {\n  const checks = await Promise.all(paths.map(d => fs.exists(path.join(d, 'node-gyp'))));\n  return checks.some(Boolean);\n}","typeGuard":"async function nodeGypOnPath(paths: string[]): Promise<boolean> {\n  const results = await Promise.all(paths.map(d => fs.exists(path.join(d, 'node-gyp'))));\n  return results.some(Boolean);\n}","tryCatchPattern":"try {\n  await ensureNodeGyp(config, reporter);\n} catch (e) {\n  if (e.message.includes('nodeGypAutoInstallFailed')) {\n    // install node-gyp manually, then re-run the lifecycle script\n  }\n}","preventionTips":["Pre-install node-gyp globally in CI images","Ensure Python and a C++ compiler are available for native builds","Whitelist registry access in corporate proxies","Cache the global node_modules layer to speed up rebuilds"],"tags":["node-gyp","native-modules","lifecycle-script"],"backgroundTag":null,"analyzedSha":"c2dda503f3759b5be5f0e24ecd9cf5c97a540147","analyzedAt":"2026-08-13T04:17:06.305Z","schemaVersion":2},"datasetVersion":"2026-08-13T09:17:06.757Z"}