What causes "Unsupported host platform {sys.platform!r}" in nodejs/node?

Pass --os explicitly (win|mac|linux|freebsd) to bypass host detection when you know the target.

nodejs/node · error · ValueError

Unsupported host platform {sys.platform!r}

Error message

Unsupported host platform {sys.platform!r}

What it means

detect_os_name() narrows sys.platform to one of win/mac/linux/freebsd so the rest of generate-headers.py can pick the right libffi platform branch. Anything else (aix, solaris, cygwin, emscripten, etc.) falls through and is rejected, because no header-generation path exists for it.

Source

Thrown at deps/libffi/generate-headers.py:216

        encoding='utf-8')
    (output_dir / 'fficonfig.h').write_text(
        render_fficonfig(os_name, target_arch),
        encoding='utf-8')
    (output_dir / 'ffitarget.h').write_text(
        ffitarget_src.read_text(encoding='utf-8'),
        encoding='utf-8')


def detect_os_name():
    if sys.platform.startswith('win'):
        return 'win'
    if sys.platform == 'darwin':
        return 'mac'
    if sys.platform.startswith('linux'):
        return 'linux'
    if sys.platform.startswith('freebsd'):
        return 'freebsd'
    raise ValueError(f'Unsupported host platform {sys.platform!r}')


def detect_target_arch():
    candidates = [
        os.environ.get('TARGET_ARCH'),
        os.environ.get('npm_config_arch'),
        os.environ.get('VSCMD_ARG_TGT_ARCH'),
        os.environ.get('Platform'),
        os.environ.get('PROCESSOR_ARCHITECTURE'),
        platform.machine(),
    ]

    aliases = {
        'amd64': 'x64',
        'x86_64': 'x64',
        'x64': 'x64',
        'win32': 'x64',
        'i386': 'ia32',

View on GitHub (pinned to 1b2de5e052)

Solutions

Pass --os explicitly (win|mac|linux|freebsd) to bypass host detection when you know the target.
If you're genuinely on a 4th-class platform, extend detect_os_name() and add the matching get_target()/has_long_double() branches.
Run under a supported container/host if you only need the headers generated.

Example fix

# before: host is aix, auto-detect fails
python generate-headers.py --output-dir out --target-arch ppc64
# after
python generate-headers.py --output-dir out --target-arch ppc64 --os linux

Defensive patterns

Strategy: validation

Validate before calling

import sys
KNOWN = ('win','mac','linux','freebsd')
os_name = args.os or ('win' if sys.platform.startswith('win') else
                    'mac' if sys.platform=='darwin' else
                    'linux' if sys.platform.startswith('linux') else
                    'freebsd' if sys.platform.startswith('freebsd') else None)
assert os_name in KNOWN, f'unsupported host {sys.platform!r}; pass --os explicitly'

Prevention

Always pass --os explicitly in CI instead of relying on host detection.
Document the four supported os values in your build README.

When it happens

Trigger: Raised at the end of detect_os_name() when sys.platform doesn't start with 'win', equal 'darwin', start with 'linux', or start with 'freebsd'. Only fires when --os is not passed on the CLI and the host must be auto-detected.

Common situations: Building on AIX, Solaris/illumos, Haiku, or under emscripten/wasi where sys.platform is something unexpected; outdated Python reporting a non-standard platform string; CI on niche OSes.

Related errors

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