How to fix npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat '/usr/include/node/common.gypi' in npm

npmINTERMEDIATEMEDIUMUpdated Dec 5, 2025· 135 views

This error occurs when node-gyp can't find the Node.js development headers needed to compile native modules. Usually caused by missing or corrupted header files.

Quick fix

Fixes npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat '/usr/include/node/common.gypi'

node-gyp install
  1. Download Node.js headers
  2. Clear and re-download headers
  3. Install Node.js development package (Linux)
  4. Set nodedir explicitly
npm — error
node-gyp install
npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat '/usr/include/node/common.gypi'

What this error means

The ENOENT error for `common.gypi` means node-gyp can't find the Node.js development headers. These headers contain the C/C++ definitions needed to compile native modules that interface with Node.js internals. node-gyp looks for these headers in several locations: - Downloaded in ~/.node-gyp/ - System-installed in /usr/include/node/ - Bundled with Node.js installation This error typically occurs when: - Headers weren't downloaded for your Node.js version - Headers are corrupted or incomplete - Using a Node.js version installed without headers - The nodedir configuration points to wrong location

Typical symptoms

  • npm install fails with ENOENT for common.gypi
  • Error mentions /usr/include/node/ or .node-gyp directory
  • Native module compilation fails to start
  • Happens after Node.js version change

Common causes

  1. Node.js development headers not installed
  2. Headers corrupted or incomplete in .node-gyp
  3. Node.js installed without development files
  4. nodedir config pointing to wrong location
  5. Version mismatch between Node.js and cached headers

How to fix "npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat '/usr/include/node/common.gypi'"

1Download Node.js headers

Tell node-gyp to download headers for your Node.js version:

bash
node-gyp install

This downloads headers to ~/.node-gyp/ (or %USERPROFILE%\.node-gyp on Windows).

2Clear and re-download headers

If headers are corrupted, remove and re-download:

bash
# Remove cached headers
rm -rf ~/.node-gyp

# Re-download
node-gyp install

# Retry npm install
npm install
3Install Node.js development package (Linux)

If using system Node.js, install the dev package:

Debian/Ubuntu:

bash
sudo apt-get install nodejs-dev

RHEL/CentOS/Fedora:

bash
sudo yum install nodejs-devel
# or
sudo dnf install nodejs-devel
4Set nodedir explicitly

Point node-gyp to the correct headers location:

bash
# Find your Node.js version
node --version

# Set nodedir (adjust path as needed)
npm config set nodedir ~/.node-gyp/$(node --version | cut -c 2-)

# Or for a single install
npm install --nodedir=/path/to/node/headers
5Upgrade node-gyp

Older node-gyp versions may have issues finding headers:

bash
npm install -g node-gyp@latest

Advanced notes

nvm users: When switching Node.js versions with nvm, headers for the new version may not exist. Run node-gyp install after switching versions.

Offline environments: If you can't download headers, you can manually copy them from another machine. Place them in ~/.node-gyp/VERSION/.

Header version matching: The headers must match your exact Node.js version. node-gyp uses your current Node.js version to determine which headers to download.

System vs nvm Node.js: If you have both system Node.js and nvm, ensure you're using consistent versions. Mixing can cause header mismatches:

bash
which node  # Check which Node.js is being used
node --version

Frequently asked questions

What does "npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat" mean?
js development headers. js internals.
How do I fix "npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat"?
This error occurs when node-gyp can't find the Node.js development headers needed to compile native modules. Usually caused by missing or corrupted header files.
What causes "npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat"?
Node.js development headers not installed Headers corrupted or incomplete in .node-gyp Node.js installed without development files
Is the "npm ERR! gyp ERR! stack Error: ENOENT: no such file or directory, stat" error serious?
It is a medium-severity error — more of a blocker than a risk. The steps above resolve it.

Official resources & further reading