yarnpkg/yarn · error · MessageError

nodeGypAutoInstallFailed

Error message

nodeGypAutoInstallFailed

What it means

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.

Source

Thrown at src/util/execute-lifecycle-script.js:322

  return checkGypPromise;
}

async function _checkForGyp(config: Config, paths: Array<string>): Promise<void> {
  const {reporter} = config;

  // Check every directory in the PATH
  const allChecks = await Promise.all(paths.map(dir => fs.exists(path.join(dir, 'node-gyp'))));
  if (allChecks.some(Boolean)) {
    // node-gyp is available somewhere
    return;
  }

  reporter.info(reporter.lang('packageRequiresNodeGyp'));

  try {
    await globalRun(config, reporter, {}, ['add', 'node-gyp']);
  } catch (e) {
    throw new MessageError(reporter.lang('nodeGypAutoInstallFailed', e.message));
  }
}

export async function execFromManifest(config: Config, commandName: string, cwd: string): Promise<void> {
  const pkg = await config.maybeReadManifest(cwd);
  if (!pkg || !pkg.scripts) {
    return;
  }

  const cmd: ?string = pkg.scripts[commandName];
  if (cmd) {
    await execCommand({stage: commandName, config, cmd, cwd, isInteractive: true});
  }
}

export async function execCommand({
  stage,
  config,

View on GitHub (pinned to c2dda503f3)

Solutions

1. Install node-gyp globally beforehand: npm install -g node-gyp
2. Ensure native build tools (Python, C++ compiler, make) are installed
3. Check network/proxy settings allow registry access for the global install
4. Run the install with appropriate write permissions for global node_modules

import * as path from 'path';
async function isNodeGypAvailable(paths: string[]): Promise<boolean> {
  const checks = await Promise.all(paths.map(d => fs.exists(path.join(d, 'node-gyp'))));
  return checks.some(Boolean);
}

async function nodeGypOnPath(paths: string[]): Promise<boolean> {
  const results = await Promise.all(paths.map(d => fs.exists(path.join(d, 'node-gyp'))));
  return results.some(Boolean);
}

try {
  await ensureNodeGyp(config, reporter);
} catch (e) {
  if (e.message.includes('nodeGypAutoInstallFailed')) {
    // install node-gyp manually, then re-run the lifecycle script
  }
}

When it happens

Trigger: 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.

Common situations: Restricted CI environments; corporate proxies blocking the install; permission errors on the global node_modules directory; running offline.

AI-assisted analysis of yarnpkg/yarn@c2dda503f3 (2026-08-13). Data as JSON: /api/errors/943aed2fec6b60af. Report an issue: GitHub.