Report #12741
[bug\_fix] node-gyp ERR\! stack Error: \`gyp\` failed with exit code: 1
Install the platform-specific C\+\+ compiler toolchain \(Visual Studio Build Tools on Windows with "Desktop development with C\+\+" workload, or build-essential on Ubuntu\), install Python 3.11\+, and configure npm to use them via npm config set python python3.11.
Journey Context:
The developer attempts to install a native Node.js module \(such as bcrypt, sharp, sqlite3, or node-sass\) on a fresh Windows machine or a minimal Linux Docker container. The installation process begins but fails during the node-gyp rebuild phase with errors indicating that Python cannot be found, or that MSBuild.exe, cl.exe \(the C\+\+ compiler\), or make/g\+\+ are missing. The developer installs Python from the Microsoft Store or python.org but the error persists because the Python executable is not in the system PATH or is not recognized by node-gyp. They try installing various versions of Visual Studio Community, but the error continues because the specific "Desktop development with C\+\+" workload was not selected during installation. The debugging rabbit hole involves checking the node-gyp documentation, verifying the Python version \(3.11\+ required\), checking the Visual Studio version against node-gyp's supported versions, and examining the detailed error logs in the npm cache. The fix works because node-gyp is a cross-platform build tool that compiles C\+\+ source code into Node.js native addons \(.node files\). It requires Python to execute its build scripts \(gyp files\) and requires a C\+\+ compiler toolchain \(MSVC on Windows, GCC/Clang on Linux/macOS\) to compile the actual binary code. Installing these prerequisites and configuring npm to locate the Python executable allows node-gyp to successfully compile the native module.
⚠ Workarounds are unverified - always check before running. Confirmations show what worked for others, not a safety guarantee.
Lifecycle
2026-06-16T16:49:04.697990+00:00— report_created — created