node-gyp fails to detect Windows SDK despite complete VS2022 BuildTools installation

# node-gyp fails to detect Windows SDK despite complete VS2022 BuildTools installation

## Environment

- **OS:** Windows 11 Pro (Build 10.0.26220)
- **Node.js:** v22.20.0 (LTS)
- **npm:** v10.9.3
- **node-gyp:** v11.2.0 (bundled with npm)
- **Python:** 3.14.0
- **Visual Studio:** Build Tools 2022 (Version 17.14.21)
- **MSVC:** v143 (14.44.35207)
- **Windows SDK:** 10.0.19041.0, 10.0.22621.0, 10.0.26100.6901, 10.0.26624.0 (standalone)

## Problem Description

`node-gyp` **fails to detect Windows SDK** when compiling native modules, despite having:
- ✅ Complete Visual Studio 2022 Build Tools installation (~15 GB)
- ✅ All Windows SDK versions installed (both via VS Installer and standalone installer)
- ✅ All required workloads and components installed
- ✅ Physical verification that all files exist on disk

### Error Output

```
gyp ERR! find VS msvs_version not set from command line or npm config
gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer
gyp ERR! find VS
gyp ERR! find VS **************************************************************
gyp ERR! find VS You need to install the latest version of Visual Studio
gyp ERR! find VS including the "Desktop development with C++" workload.
gyp ERR! find VS For more information consult the documentation at:
gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows
gyp ERR! find VS **************************************************************
gyp ERR! find VS
gyp ERR! configure error
gyp ERR! stack Error: Could not find any Visual Studio installation to use
```

### What node-gyp Detects vs. Reality

**node-gyp reports:**
```
gyp ERR! find VS - found "Visual Studio C++ core features"
gyp ERR! find VS - found VC++ toolset: v143
gyp ERR! find VS - missing any Windows SDK
```

**Physical verification shows everything exists:**
```cmd
C:\Program Files (x86)\Windows Kits\10\
├── Include\10.0.26624.0\    ✅ EXISTS (created 2025-12-04 19:19)
│   ├── um\
│   ├── ucrt\
│   ├── shared\
│   └── winrt\
└── Lib\10.0.26624.0\        ✅ EXISTS (created 2025-12-04 19:19)
    ├── um\x64\
    ├── ucrt\x64\
    └── [others]

C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\lib\x64\delayimp.lib
✅ EXISTS (137,570 bytes, created 2025-12-04 15:30)
```

## What I've Tried

### Time Invested
**4 hours 19 minutes** across **21 troubleshooting iterations**

### Installation Attempts

#### 1. Spectre Mitigation Libraries ✅ Resolved initial error
```cmd
# Installed via Visual Studio Installer > Individual Components
- MSVC v143 - VS 2022 C++ x64/x86 Spectre-mitigated libs (Latest)
```
**Result:** Fixed MSB8040 error, but revealed next issue

#### 2. Node.js Version Correction ✅ Resolved C++20 requirement
```cmd
# Downgraded from v25.2.1 to v22.20.0 (as required by VSCode's .nvmrc)
nvm install 22.20.0
nvm use 22.20.0
```
**Result:** Fixed C++20 error, but revealed DelayImp.lib issue

#### 3. Complete Build Tools Installation ❌ Did not resolve
```cmd
# Installed full workload via Visual Studio Installer
- Desktop development with C++ (~10 GB)
- Including all recommended components
```
**Duration:** 45 minutes
**Result:** Files installed correctly, but node-gyp still failed

#### 4. Windows SDK via Visual Studio Installer ❌ Did not resolve
```cmd
# Installed multiple SDK versions via VS Installer > Individual Components
- Windows 10 SDK (10.0.19041.0)
- Windows 11 SDK (10.0.22621.0)
- Windows 11 SDK (10.0.26100.6901)
```
**Result:** SDKs installed but not registered properly for node-gyp detection

#### 5. Windows SDK Standalone Installer ❌ Did not resolve
```cmd
# Downloaded and installed from Microsoft:
# https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/
# Version: 10.0.26624.0 (~3.5 GB)
# Selected all components including:
- Windows SDK for Desktop C++ x86/x64/arm64 Apps
- Debugging Tools for Windows
- Windows Performance Toolkit
```
**Duration:** 30 minutes
**Result:** Created all required folders but node-gyp still doesn't detect it

#### 6. Manual delayimp.lib Copy ❌ Did not resolve
```cmd
# Copied delayimp.lib from MSVC to Windows SDK location
copy "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\lib\x64\delayimp.lib" ^
     "C:\Program Files (x86)\Windows Kits\10\Lib\10.0.22621.0\um\x64\"
```
**Result:** File copied successfully but node-gyp still fails

### Configuration Attempts

#### 7. Environment Variables (Manual) ❌ Did not resolve
```cmd
set "LIB=C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\lib\x64;%LIB%"
set "INCLUDE=C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\include;%INCLUDE%"
set "PATH=C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\bin\Hostx64\x64;%PATH%"
npm install
```
**Result:** Failed with same error

#### 8. vcvarsall.bat ❌ Did not resolve
```cmd
cmd /c "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Auxiliary\Build\vcvarsall.bat" x64 && npm install
```
**Result:** Failed with same error

#### 9. VsDevCmd.bat ❌ Did not resolve
```cmd
"C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\Common7\Tools\VsDevCmd.bat" && npm install
```
**Result:** Failed with same error

#### 10. npm config (attempted) ❌ Commands invalid
```cmd
npm config set msvs_version 2022
# Error: `msvs_version` is not a valid npm option

npm config set python C:\Users\Eduardo\AppData\Local\Python\pythoncore-3.14-64\python.exe
# Error: `python` is not a valid npm option
```
**Result:** npm doesn't accept these config options in v10.9.3

### Cache and Cleanup Attempts

#### 11. Complete Cache Cleanup ✅ Changed error message (progress)
```powershell
Remove-Item $env:LOCALAPPDATA\node-gyp -Recurse -Force
Remove-Item $env:LOCALAPPDATA\npm-cache -Recurse -Force
Remove-Item D:\proj\mini\node_modules -Recurse -Force
npm cache clean --force
```
**Result:** Error changed from "DelayImp.lib missing" to "Windows SDK missing"

#### 12. PC Restarts ❌ Did not resolve
**Attempts:** 2 full system restarts
**Result:** No change

### Workaround Attempts

#### 13. --ignore-scripts ⚠️ Partial success
```cmd
npm install --legacy-peer-deps --ignore-scripts
```
**Result:** Installed 1612 packages successfully, but native modules not compiled

#### 14. Selective rebuild ❌ Did not resolve
```cmd
npm rebuild @parcel/watcher --ignore-scripts
# Output: "rebuilt dependencies successfully"
# But actually did nothing (due to --ignore-scripts)

npm rebuild @parcel/watcher
# Failed with same SDK detection error
```

## Verification Commands

### vswhere.exe (Official Microsoft Tool)
```cmd
"C:\Program Files (x86)\Microsoft Visual Studio\Installer\vswhere.exe" ^
  -products * ^
  -requires Microsoft.VisualStudio.Component.Windows11SDK.22621 ^
  -property installationPath

# Result: (empty)
# Interpretation: SDK component not properly registered despite appearing in VS Installer UI
```

### Physical File Verification
```cmd
dir "C:\Program Files (x86)\Windows Kits\10\"
# Result: 20 folders including Include\ and Lib\ (created 2025-12-04 19:19)

dir "C:\Program Files (x86)\Windows Kits\10\Include\10.0.26624.0"
# Result: um\, ucrt\, shared\, winrt\ folders all exist

dir "C:\Program Files (x86)\Windows Kits\10\Lib\10.0.26624.0"
# Result: um\x64\, ucrt\x64\ folders exist

dir "C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.44.35207\lib\x64\delayimp.lib"
# Result: File exists (137,570 bytes)
```

## Root Cause Analysis

### The Paradox
- ✅ **Visual Studio 2022 Build Tools** is detected by node-gyp
- ✅ **MSVC v143 toolset** is detected by node-gyp
- ✅ **Python 3.14** is detected by node-gyp
- ✅ **All physical files and folders** exist on disk
- ❌ **Windows SDK** is NOT detected by node-gyp

### Hypothesis
Based on analysis of `find-visualstudio.js`, node-gyp searches for **component IDs registered in Visual Studio**, not just folder existence:

```javascript
// From node-gyp source code
const win11SDKPrefix = 'Microsoft.VisualStudio.Component.Windows11SDK.'
const win10SDKPrefix = 'Microsoft.VisualStudio.Component.Windows10SDK.'
```

**The issue:** Windows SDK installed via standalone installer creates folders but doesn't register these component IDs in Visual Studio's metadata, causing node-gyp's detection to fail.

### Supporting Evidence

1. **vswhere.exe returns empty** when searching for SDK component
2. **Visual Studio Installer shows SDK** in UI but vswhere can't find it
3. **node-gyp detects VS2022 and MSVC** but not SDK (partial detection)
4. **Manual environment variables don't help** (node-gyp uses its own detection logic)

## Expected Behavior

node-gyp should detect the Windows SDK when:
1. Windows SDK is installed via Visual Studio Installer, OR
2. Windows SDK is installed via standalone installer and creates standard folder structure, OR
3. Environment variables (INCLUDE, LIB, PATH) are properly set

## Actual Behavior

node-gyp fails with "missing any Windows SDK" error despite:
- Multiple SDK versions installed (~15 GB total)
- All folder structures created correctly
- All files existing and verified
- Environment variables configured

## Impact

**Blocks compilation of VSCode fork** and any other project requiring native Node.js modules:
- `@parcel/watcher@2.5.1` (file watching)
- `native-is-elevated` (elevation detection)
- `@vscode/policy-watcher` (policy monitoring)

## Additional Information

### Affected Module
```json
{
  "name": "@parcel/watcher",
  "version": "2.5.1",
  "repository": "git://github.com/parcel-bundler/watcher.git"
}
```

### Full Error Log
```
npm error gyp ERR! find VS msvs_version not set from command line or npm config
npm error gyp ERR! find VS VCINSTALLDIR not set, not running in VS Command Prompt
npm error gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer, try re-running with '--loglevel silly' for more details.
npm error gyp ERR! find VS
npm error gyp ERR! find VS Failure details: undefined
npm error gyp ERR! find VS could not use PowerShell to find Visual Studio 2017 or newer, try re-running with '--loglevel silly' for more details.
npm error gyp ERR! find VS
npm error gyp ERR! find VS Failure details: undefined
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2017 as it is only supported up to Node.js 21
npm error gyp ERR! find VS not looking for VS2015 as it is only supported up to Node.js 18
npm error gyp ERR! find VS not looking for VS2013 as it is only supported up to Node.js 8
npm error gyp ERR! find VS
npm error gyp ERR! find VS **************************************************************
npm error gyp ERR! find VS You need to install the latest version of Visual Studio
npm error gyp ERR! find VS including the "Desktop development with C++" workload.
npm error gyp ERR! find VS For more information consult the documentation at:
npm error gyp ERR! find VS https://github.com/nodejs/node-gyp#on-windows
npm error gyp ERR! find VS **************************************************************
npm error gyp ERR! find VS
npm error gyp ERR! configure error
npm error gyp ERR! stack Error: Could not find any Visual Studio installation to use
npm error gyp ERR! stack     at VisualStudioFinder.fail (D:\app\dev\nvm\v22.20.0\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:118:11)
npm error gyp ERR! stack     at VisualStudioFinder.findVisualStudio (D:\app\dev\nvm\v22.20.0\node_modules\npm\node_modules\node-gyp\lib\find-visualstudio.js:74:17)
npm error gyp ERR! stack     at process.processTicksAndRejections (node:internal/process/task_queues:105:5)
npm error gyp ERR! stack     at async createBuildDir (D:\app\dev\nvm\v22.20.0\node_modules\npm\node_modules\node-gyp\lib\configure.js:112:18)
npm error gyp ERR! stack     at async run (D:\app\dev\nvm\v22.20.0\node_modules\npm\node_modules\node-gyp\bin\node-gyp.js:81:18)
npm error gyp ERR! System Windows_NT 10.0.26220
npm error gyp ERR! command "D:\\app\\dev\\nodejs\\node.exe" "D:\\app\\dev\\nvm\\v22.20.0\\node_modules\\npm\\node_modules\\node-gyp\\bin\\node-gyp.js" "rebuild"
npm error gyp ERR! cwd C:\Users\Eduardo\AppData\Local\npm-cache\_cacache\tmp\git-clonex4D6SL
npm error gyp ERR! node -v v22.20.0
npm error gyp ERR! node-gyp -v v11.2.0
npm error gyp ERR! not ok
```

## Questions

1. **Is this a known issue with VS2022 Build Tools?** (vs. full IDE installation)
2. **Should standalone Windows SDK installer register components in Visual Studio?**
3. **Is there a way to manually register SDK components** for node-gyp detection?
4. **Are there environment variables** that node-gyp respects beyond VCINSTALLDIR?
5. **Should node-gyp fall back to folder detection** when component registration fails?

## Possible Workarounds (untested)

1. **Install Visual Studio Community 2022** (full IDE ~30 GB) instead of Build Tools
2. **Use WSL2** with Ubuntu for building native modules
3. **Use Docker** with Windows SDK pre-configured
4. **Use pre-compiled binaries** from CI/CD (GitHub Actions)
5. **Modify node-gyp source** to accept folder-based detection

## Request

Could you please:
1. Confirm if this is a bug in node-gyp's Visual Studio detection logic
2. Provide guidance on how to properly register standalone Windows SDK for node-gyp
3. Consider adding fallback detection based on folder structure when component IDs are missing
4. Update documentation to clarify whether Build Tools is sufficient or full IDE is required

## System Details

```yaml
Operating System:
  Name: Windows 11 Pro
  Version: 10.0.26220
  Architecture: x64

Node.js:
  Version: v22.20.0
  npm: v10.9.3
  node-gyp: v11.2.0 (bundled)

Python:
  Version: 3.14.0
  Path: C:\Users\Eduardo\AppData\Local\Python\pythoncore-3.14-64\python.exe

Visual Studio Build Tools 2022:
  Version: 17.14.21
  Instance ID: b6487840
  Path: C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools
  
MSVC:
  Version: 14.44.35207 (primary)
  Version: 14.38.33130 (legacy)
  Toolset: v143
  
Components Installed:
  - Desktop development with C++ (complete workload)
  - MSVC v143 build tools
  - Spectre-mitigated libraries (x64/x86)
  - ATL for v143
  - MFC for v143
  - CMake tools
  - AddressSanitizer
  - vcpkg package manager
  - Clang C++ tools for Windows

Windows SDK Versions:
  Via VS Installer:
    - 10.0.19041.0
    - 10.0.22621.0
    - 10.0.26100.6901
  Via Standalone Installer:
    - 10.0.26624.0 (3.5 GB installation)

Disk Space Used:
  - Visual Studio Build Tools: ~15 GB
  - Windows SDK: ~3.5 GB
  - Total: ~18.5 GB
```

---

**Thank you for your time investigating this issue. After 4+ hours of troubleshooting with complete installations, I'm confident this is either a bug in node-gyp's detection logic or a gap in the documentation regarding Build Tools vs. full IDE requirements.**

Uh oh!

node-gyp fails to detect Windows SDK despite complete VS2022 BuildTools installation #3251

Description

node-gyp fails to detect Windows SDK despite complete VS2022 BuildTools installation

Environment

Problem Description

Error Output

What node-gyp Detects vs. Reality

What I've Tried

Time Invested

Installation Attempts

1. Spectre Mitigation Libraries ✅ Resolved initial error

2. Node.js Version Correction ✅ Resolved C++20 requirement

3. Complete Build Tools Installation ❌ Did not resolve

4. Windows SDK via Visual Studio Installer ❌ Did not resolve

5. Windows SDK Standalone Installer ❌ Did not resolve

6. Manual delayimp.lib Copy ❌ Did not resolve

Configuration Attempts

7. Environment Variables (Manual) ❌ Did not resolve

8. vcvarsall.bat ❌ Did not resolve

9. VsDevCmd.bat ❌ Did not resolve

10. npm config (attempted) ❌ Commands invalid

Cache and Cleanup Attempts

11. Complete Cache Cleanup ✅ Changed error message (progress)

12. PC Restarts ❌ Did not resolve

Workaround Attempts

13. --ignore-scripts ⚠️ Partial success

14. Selective rebuild ❌ Did not resolve

Verification Commands

vswhere.exe (Official Microsoft Tool)

Physical File Verification

Root Cause Analysis

The Paradox

Hypothesis

Supporting Evidence

Expected Behavior

Actual Behavior

Impact

Additional Information

Affected Module

Full Error Log

Questions

Possible Workarounds (untested)

Request

System Details

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions