{"record":{"id":"92bbc3790e8da1f3","repo":"nodejs/node","slug":"could-not-locate-visual-studio-installation","errorCode":null,"errorMessage":"Could not locate Visual Studio installation.","messagePattern":"Could not locate Visual Studio installation\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"tools/gyp/pylib/gyp/MSVSVersion.py","lineNumber":601,"sourceCode":"        \"2015\": (\"14.0\",),\n        \"2017\": (\"15.0\",),\n        \"2019\": (\"16.0\",),\n        \"2022\": (\"17.0\",),\n        \"2026\": (\"18.0\",),\n    }\n    if override_path := os.environ.get(\"GYP_MSVS_OVERRIDE_PATH\"):\n        msvs_version = os.environ.get(\"GYP_MSVS_VERSION\")\n        if not msvs_version:\n            raise ValueError(\n                \"GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be \"\n                \"set to a particular version (e.g. 2010e).\"\n            )\n        return _CreateVersion(msvs_version, override_path, sdk_based=True)\n    version = str(version)\n    versions = _DetectVisualStudioVersions(version_map[version], \"e\" in version)\n    if not versions:\n        if not allow_fallback:\n            raise ValueError(\"Could not locate Visual Studio installation.\")\n        if version == \"auto\":\n            # Default to 2005 if we couldn't find anything\n            return _CreateVersion(\"2005\", None)\n        else:\n            return _CreateVersion(version, None)\n    return versions[0]\n","sourceCodeStart":583,"sourceCodeEnd":608,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/tools/gyp/pylib/gyp/MSVSVersion.py#L583-L608","documentation":"When neither override mechanism nor fallback resolves a Visual Studio install, _GetVisualStudioVersion raises ValueError('Could not locate Visual Studio installation.'). _DetectVisualStudioVersions returned an empty list for the requested version key, and allow_fallback is False, so gyp refuses to silently pick a wrong toolchain. (When allow_fallback is True and version=='auto', gyp falls back to VS2005 or the requested version with a None path.)","triggerScenarios":"Running gyp -f msvs on a machine with no Visual Studio installed; requesting a specific version (e.g. GYP_MSVS_VERSION=2019) that isn't present and fallback is disabled; registry/where/wmic detection all coming up empty.","commonSituations":"Clean CI Windows image without Build Tools; VS installed only for a different user account; bit-ness mismatch (only x86 VS detected but x64 requested).","solutions":["Install Visual Studio (or the standalone Build Tools) for the requested version, including the C++ workload.","Set GYP_MSVS_VERSION to a version that is actually installed, or 'auto' to let gyp detect.","Set GYP_MSVS_OVERRIDE_PATH + GYP_MSVS_VERSION to point at a known install location.","Re-run with allow_fallback enabled if a best-effort match is acceptable."],"exampleFix":"# before: no VS, version pinned\nset GYP_MSVS_VERSION=2019\npython gyp\n\n# after: install Build Tools 2022, then auto-detect\nset GYP_MSVS_VERSION=auto\npython gyp","handlingStrategy":"fallback","validationCode":"import subprocess\ndef vs_installed():\n    try:\n        subprocess.check_output(['vswhere', '-latest', '-property', 'installationPath'], stderr=subprocess.DEVNULL)\n        return True\n    except Exception:\n        return False\nif not vs_installed():\n    raise SystemExit('No Visual Studio detected. Install VS or Build Tools with the C++ workload.')","typeGuard":"def visual_studio_available(version: str = 'auto') -> bool:\n    try:\n        _GetVisualStudioVersion(version)\n        return True\n    except Exception:\n        return False","tryCatchPattern":"try:\n    vs = _GetVisualStudioVersion('2019')\nexcept ValueError:\n    vs = _GetVisualStudioVersion('auto', allow_fallback=True)  # best-effort fallback","preventionTips":["Install Visual Studio Build Tools with the C++ workload on every Windows build agent.","Set GYP_MSVS_VERSION=auto unless a specific version is required.","Use vswhere to verify an install exists before invoking gyp."],"tags":["gyp","msvs","visual-studio","windows","toolchain","detection"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}