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.
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.
node-pre-gyp needs build tools for fallback compilation:
Linux (Debian/Ubuntu):
sudo apt-get update
sudo apt-get install -y build-essential python3macOS:
xcode-select --installWindows (run as Administrator):
npm install --global --production windows-build-toolsPrebuilt binaries are usually available for LTS versions:
# Switch to LTS
nvm install --lts
nvm use --lts
# Clean install
rm -rf node_modules package-lock.json
npm installClear any corrupted state:
npm cache clean --force
rm -rf node_modules package-lock.json
npm installSome platforms need extra setup:
Alpine Linux:
apk add --no-cache python3 make g++Windows - if Windows SDK errors:
Install Visual Studio with "Desktop development with C++" workload.
Permission issues:
npm install --unsafe-permIf compilation keeps failing, use pure JS alternatives:
| Native Package | JS Alternative |
|---------------|----------------|
| bcrypt | bcryptjs |
| sqlite3 | better-sqlite3, sql.js |
| node-sass | sass |
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:
npm install --verboseBuild from source explicitly:
npm install --build-from-sourceDocker optimization: In multi-stage builds, compile in a full image:
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_modulesCI/CD caching: Cache node_modules in CI to avoid rebuilding native modules on every run.
npm ERR! code E401 npm ERR! 401 Unauthorized - Token has expired
Token has expired - npm authentication failure
npm ERR! code EAI_NODATA npm ERR! errno EAI_NODATA npm ERR! getaddrinfo EAI_NODATA registry.npmjs.org
How to fix "npm ERR! code EAI_NODATA - getaddrinfo EAI_NODATA"
npm ERR! code EMPTYPACKAGE npm ERR! Package contains no files
How to fix 'npm ERR! code EMPTYPACKAGE' - Package contains no files
npm ERR! code EWORKSPACEMISSING npm ERR! Workspace does not exist: packages/missing
How to fix "npm ERR! code EWORKSPACEMISSING - Workspace does not exist" error
npm ERR! code EADDRNOTAVAIL npm ERR! errno EADDRNOTAVAIL npm ERR! Address not available
How to fix "npm ERR! code EADDRNOTAVAIL - Address not available" error