This error occurs when node-gyp fails to configure the build environment for native Node.js addons. It typically happens due to missing build tools, incompatible Python versions, or missing Visual Studio components on Windows.
The "gyp ERR! configure error" indicates that node-gyp, Node.js's build tool for native addons, cannot set up the compilation environment. node-gyp is used by many npm packages that include native C/C++ code (like bcrypt, node-sass, sqlite3, and others) to compile platform-specific binaries during installation. This error occurs during the configuration phase, before any actual compilation happens. node-gyp needs to detect your system's Python installation, C++ compiler, and other build tools. When any of these prerequisites are missing, misconfigured, or incompatible, the configuration step fails. The error is especially common on Windows where Visual Studio Build Tools are required, but it can also occur on macOS (missing Xcode Command Line Tools) and Linux (missing build-essential packages).
Check if Python is installed and accessible:
python --version
# or
python3 --versionnode-gyp requires Python 3.6 or later. If Python is not installed or the version is too old, download and install Python from [python.org](https://www.python.org/downloads/).
Important: During installation on Windows, check the box "Add Python to PATH".
If you have multiple Python versions, configure npm to use a specific version:
npm config set python /path/to/python3Windows:
Install Visual Studio Build Tools with C++ support:
npm install --global windows-build-toolsOr manually download [Visual Studio Build Tools 2022](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) and select "Desktop development with C++" workload during installation.
macOS:
Install Xcode Command Line Tools:
xcode-select --installLinux/Ubuntu:
Install build-essential package:
sudo apt-get update
sudo apt-get install build-essentialRemove corrupted cache and dependencies:
# Clear npm cache
npm cache clean --force
# Remove existing node_modules and lock file
rm -rf node_modules package-lock.json
# Reinstall dependencies
npm installOn Windows PowerShell:
npm cache clean --force
Remove-Item -Recurse -Force node_modules
Remove-Item package-lock.json
npm installIf you have multiple Visual Studio versions installed, specify which one to use:
npm config set msvs_version 2022For Visual Studio 2019:
npm config set msvs_version 2019You can also set this per-install:
npm install --msvs_version=2022Some native modules have compatibility issues with newer Node.js versions. Try switching to an LTS version:
# Using nvm (Node Version Manager)
nvm install --lts
nvm use --lts
# Verify version
node --versionThen try installing again:
npm installAvoiding node-gyp altogether: Consider migrating to packages that don't require native compilation. For example, use bcryptjs instead of bcrypt, or sass instead of node-sass. These pure JavaScript alternatives avoid the node-gyp dependency entirely.
PowerShell improvements (Windows): Install the VSSetup PowerShell module for better Visual Studio detection:
Install-Module VSSetup -Scope CurrentUserProxy/network issues: If you're behind a corporate proxy, node-gyp may fail to download dependencies. Configure npm proxy settings:
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080CI/CD environments: For Docker or CI pipelines, install build tools in your base image to avoid repeated installations. For Alpine Linux, use apk add python3 make g++. For Debian/Ubuntu, use apt-get install python3 build-essential.
Debugging: Run npm install with verbose logging to see exactly where configuration fails:
npm install --verboseError: Listener already called (once event already fired)
EventEmitter listener already called with once()
Error: EACCES: permission denied, open '/root/file.txt'
EACCES: permission denied
Error: Invalid encoding specified (stream encoding not supported)
How to fix Invalid encoding error in Node.js readable streams
Error: EINVAL: invalid argument, open
EINVAL: invalid argument, open
TypeError: readableLength must be a positive integer (stream config)
TypeError: readableLength must be a positive integer in Node.js streams