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 compiler

The fix

# Linux: sudo apt install build-essential python3
# macOS: xcode-select --install
npm install bcrypt

Prefer pure JS or prebuilt

npm install bcryptjs   # no native build
nvm use 20

Common 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.

More JavaScript articles