How to fix npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stack Error: Failed to execute in npm

npmINTERMEDIATEHIGHUpdated Dec 5, 2025· 125 views

This error occurs when node-pre-gyp can't find prebuilt binaries and fails to compile from source. Usually caused by missing build tools or unsupported platform.

Quick fix

Fixes npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stack Error: Failed to execute

sudo apt-get update
sudo apt-get install -y build-essential python3
  1. Install build tools
  2. Use supported Node.js version
  3. Clean and retry
  4. Check for platform-specific issues
npm — error
sudo apt-get update
sudo apt-get install -y build-essential python3
npm ERR! node-pre-gyp ERR! build error
npm ERR! node-pre-gyp ERR! stack Error: Failed to execute

What this error means

node-pre-gyp is a tool that downloads prebuilt native module binaries. When it can't find a prebuilt binary for your platform/Node.js combination, it falls back to compiling from source using node-gyp. The "build error" means this fallback compilation failed. This is usually because: - Build tools (compiler, make, Python) aren't installed - The package doesn't support your platform - There's a version incompatibility node-pre-gyp is commonly used by packages like bcrypt, sqlite3, and grpc.

Typical symptoms

  • Error shows 'node-pre-gyp ERR! build error'
  • Stack trace mentions 'Failed to execute'
  • Happens with packages like bcrypt, sqlite3, grpc
  • Install works on some machines but fails on others

Common causes

  1. Build tools not installed (gcc, g++, make, Python)
  2. No prebuilt binary for your platform/Node.js version
  3. Windows SDK missing on Windows
  4. Xcode Command Line Tools missing on macOS
  5. Permission issues during compilation

How to fix "npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stack Error: Failed to execute"

1Install build tools

node-pre-gyp needs build tools for fallback compilation:

Linux (Debian/Ubuntu):

bash
sudo apt-get update
sudo apt-get install -y build-essential python3

macOS:

bash
xcode-select --install

Windows (run as Administrator):

powershell
npm install --global --production windows-build-tools
2Use supported Node.js version

Prebuilt binaries are usually available for LTS versions:

bash
# Switch to LTS
nvm install --lts
nvm use --lts

# Clean install
rm -rf node_modules package-lock.json
npm install
3Clean and retry

Clear any corrupted state:

bash
npm cache clean --force
rm -rf node_modules package-lock.json
npm install
4Check for platform-specific issues

Some platforms need extra setup:

Alpine Linux:

bash
apk add --no-cache python3 make g++

Windows - if Windows SDK errors:
Install Visual Studio with "Desktop development with C++" workload.

Permission issues:

bash
npm install --unsafe-perm
5Consider alternatives

If compilation keeps failing, use pure JS alternatives:

| Native Package | JS Alternative |
|---------------|----------------|
| bcrypt | bcryptjs |
| sqlite3 | better-sqlite3, sql.js |
| node-sass | sass |

Advanced notes

Deprecated package warning: The original node-pre-gyp package is deprecated. The maintained version is @mapbox/node-pre-gyp. If you're a package author, migrate to the maintained version.

Verbose output: Get more details about what's failing:

bash
npm install --verbose

Build from source explicitly:

bash
npm install --build-from-source

Docker optimization: In multi-stage builds, compile in a full image:

dockerfile
FROM node:20 AS builder
RUN apt-get update && apt-get install -y build-essential python3
WORKDIR /app
COPY package*.json ./
RUN npm ci

FROM node:20-slim
COPY --from=builder /app/node_modules ./node_modules

CI/CD caching: Cache node_modules in CI to avoid rebuilding native modules on every run.

Frequently asked questions

What does "npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stac" mean?
node-pre-gyp is a tool that downloads prebuilt native module binaries. js combination, it falls back to compiling from source using node-gyp. The "build error" means this fallback compilation failed.
How do I fix "npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stac"?
This error occurs when node-pre-gyp can't find prebuilt binaries and fails to compile from source. Usually caused by missing build tools or unsupported platform.
What causes "npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stac"?
Build tools not installed (gcc, g++, make, Python) No prebuilt binary for your platform/Node.js version Windows SDK missing on Windows
Is the "npm ERR! node-pre-gyp ERR! build error npm ERR! node-pre-gyp ERR! stac" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading