nodejs/node · error · ValueError

GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be set t

Error message

GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be set to a particular version (e.g. 2010e).

What it means

_GetVisualStudioVersion (in MSVSVersion.py) raises ValueError when the environment variable GYP_MSVS_OVERRIDE_PATH is set but GYP_MSVS_VERSION is not. The override-path mechanism lets you point gyp at a non-standard VS install location, but it requires the version tag (e.g. 2019, 2022, 2026, or an 'e' Express variant) to know which version label to construct. Without it, _CreateVersion cannot be called.

Source

Thrown at tools/gyp/pylib/gyp/MSVSVersion.py:592

        "2005e": ("8.0",),
        "2008": ("9.0",),
        "2008e": ("9.0",),
        "2010": ("10.0",),
        "2010e": ("10.0",),
        "2012": ("11.0",),
        "2012e": ("11.0",),
        "2013": ("12.0",),
        "2013e": ("12.0",),
        "2015": ("14.0",),
        "2017": ("15.0",),
        "2019": ("16.0",),
        "2022": ("17.0",),
        "2026": ("18.0",),
    }
    if override_path := os.environ.get("GYP_MSVS_OVERRIDE_PATH"):
        msvs_version = os.environ.get("GYP_MSVS_VERSION")
        if not msvs_version:
            raise ValueError(
                "GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be "
                "set to a particular version (e.g. 2010e)."
            )
        return _CreateVersion(msvs_version, override_path, sdk_based=True)
    version = str(version)
    versions = _DetectVisualStudioVersions(version_map[version], "e" in version)
    if not versions:
        if not allow_fallback:
            raise ValueError("Could not locate Visual Studio installation.")
        if version == "auto":
            # Default to 2005 if we couldn't find anything
            return _CreateVersion("2005", None)
        else:
            return _CreateVersion(version, None)
    return versions[0]

View on GitHub (pinned to 1b2de5e052)

Solutions

Set both variables together: GYP_MSVS_VERSION=2022 and GYP_MSVS_OVERRIDE_PATH=C:\Program Files\Microsoft Visual Studio\2022\Community.
Use a version string present in version_map (2022 -> 17.0, 2026 -> 18.0, or an 'e' Express variant).
If you want auto-detection instead, unset GYP_MSVS_OVERRIDE_PATH entirely.

Example fix

# before
export GYP_MSVS_OVERRIDE_PATH=/c/VS2022

# after
export GYP_MSVS_VERSION=2022
export GYP_MSVS_OVERRIDE_PATH=/c/VS2022

Defensive patterns

Strategy: validation

Validate before calling

import os
override = os.environ.get('GYP_MSVS_OVERRIDE_PATH')
version = os.environ.get('GYP_MSVS_VERSION')
if override and not version:
    raise SystemExit('Set GYP_MSVS_VERSION (e.g. 2022) when using GYP_MSVS_OVERRIDE_PATH.')

Type guard

def override_env_is_consistent() -> bool:
    import os
    o = os.environ.get('GYP_MSVS_OVERRIDE_PATH')
    v = os.environ.get('GYP_MSVS_VERSION')
    return not o or bool(v)

Try / catch

try:
    vs = _GetVisualStudioVersion('auto')
except ValueError as e:
    if 'GYP_MSVS_OVERRIDE_PATH' in str(e):
        os.environ['GYP_MSVS_VERSION'] = '2022'  # then retry
        raise

Prevention

Always set GYP_MSVS_VERSION alongside GYP_MSVS_OVERRIDE_PATH.
Validate both env vars in a wrapper script before calling gyp.
Prefer a single shell snippet that exports both variables together.

When it happens

Trigger: Exporting only GYP_MSVS_OVERRIDE_PATH=/path/to/VS without also exporting GYP_MSVS_VERSION=2022; CI scripts that set the path dynamically but forget the version.

Common situations: Custom VS install locations on build agents; redirecting gyp to a portable VS; migrating from hardcoded paths to the override mechanism and missing the second variable.

Related errors

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/1ff2c7e6c54583da. Report an issue: GitHub.