gyp ERR! in Node.js — What It Means and How to Fix It
What the Node.js/npm error gyp ERR! means and how to resolve it.
Published October 26, 2026
node-gyp compiles native add-ons (C/C++) during npm install. gyp errors mean the toolchain, Python or Node headers are missing or incompatible.
What it means and why it happens
Typical causes: missing build tools, unsupported Node version for the package, or no prebuilt binary available.
Read the full message: it names the file and line where the problem was detected, which is the best place to start.
What you see
run the code
gyp ERR! build error
gyp ERR! stack Error: `make` failed with exit code: 2
Practical examples
Code that triggers it
npm install bcrypt // needs a compilerThe fix
# Linux: sudo apt install build-essential python3
# macOS: xcode-select --install
npm install bcryptPrefer pure JS or prebuilt
npm install bcryptjs # no native build
nvm use 20Common mistakes
- Using an unsupported Node version.
- Missing Python or compiler.
- Not reading the error above gyp lines.
Key takeaways
- gyp ERR!: node-gyp compiles native add-ons (C/C++) during npm install.
- Read the message and the line number first.
- Fix the cause, don't just silence the error.
FAQ
Avoid native builds?
Choose packages with prebuilt binaries or pure JS alternatives.
How do I find which line caused gyp ERR!?
The error message and stack trace show the file and line; start there and work backwards.