nodejs/node · error · Exception

--v8-enable-hugepage is supported only on linux.

Error message

--v8-enable-hugepage is supported only on linux.

What it means

Node's configure only allows --v8-enable-hugepage on Linux. The flag maps to v8_enable_hugepage, which toggles V8's use of transparent huge pages via Linux-specific mmap hints; on macOS/Windows/freebsd there is no equivalent path so configure hard-aborts before writing the variable.

Source

Thrown at configure.py:2253

  o['variables']['force_dynamic_crt'] = 1 if options.shared else 0
  o['variables']['node_enable_d8'] = b(options.enable_d8)
  o['variables']['node_enable_v8windbg'] = b(options.enable_v8windbg)
  if options.enable_d8:
    o['variables']['test_isolation_mode'] = 'noop'  # Needed by d8.gyp.
  if options.without_bundled_v8:
    if options.enable_d8:
      raise Exception('--enable-d8 is incompatible with --without-bundled-v8.')
    if options.enable_v8windbg:
      raise Exception('--enable-v8windbg is incompatible with --without-bundled-v8.')
    (pkg_libs, pkg_cflags, pkg_libpath, _) = pkg_config("v8")
    if pkg_libs and pkg_libpath:
      output['libraries'] += [pkg_libpath] + pkg_libs.split()
    if pkg_cflags:
      output['include_dirs'] += [flag for flag in [flag.strip() for flag in pkg_cflags.split('-I')] if flag]
  if options.static_zoslib_gyp:
    o['variables']['static_zoslib_gyp'] = options.static_zoslib_gyp
  if flavor != 'linux' and options.v8_enable_hugepage:
    raise Exception('--v8-enable-hugepage is supported only on linux.')
  o['variables']['v8_enable_hugepage'] = 1 if options.v8_enable_hugepage else 0
  if options.v8_enable_short_builtin_calls or o['variables']['target_arch'] == 'x64':
    o['variables']['v8_enable_short_builtin_calls'] = 1
  if options.v8_enable_snapshot_compression:
    o['variables']['v8_enable_snapshot_compression'] = 1
  if all(opt in sys.argv for opt in ['--v8-enable-object-print', '--v8-disable-object-print']):
    raise Exception(
        'Only one of the --v8-enable-object-print or --v8-disable-object-print options '
        'can be specified at a time.')
  if all(opt in sys.argv for opt in ['--v8-enable-temporal-support', '--v8-disable-temporal-support']):
    raise Exception(
        'Only one of the --v8-enable-temporal-support or --v8-disable-temporal-support options '
        'can be specified at a time.')
  if sys.platform != 'darwin':
    if o['variables']['v8_enable_webassembly'] and o['variables']['target_arch'] == 'x64':
      o['variables']['v8_enable_wasm_simd256_revec'] = 1

def configure_openssl(o):

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Drop --v8-enable-hugepage on non-Linux targets (gate it on uname/OS in your build wrapper).
2. If you genuinely need huge pages, run that build on a Linux host.
3. Make the flag conditional in your build script: only emit it when the target OS is linux.

Example fix

// before
./configure --v8-enable-hugepage   # on macOS/Windows
// after
if [ "$(uname)" = "Linux" ]; then EXTRA="--v8-enable-hugepage"; fi
./configure $EXTRA

import platform, sys
if '--v8-enable-hugepage' in sys.argv and platform.system() != 'Linux':
    raise SystemExit('--v8-enable-hugepage is Linux-only; remove it for this OS')

When it happens

Trigger: Raised when options.v8_enable_hugepage is truthy and flavor != 'linux'. The check runs after the bundled-v8 block and before v8_enable_hugepage is assigned to o['variables'].

Common situations: Cross-platform build matrix scripts that pass the same set of perf flags on every OS; Docker builds that forgot the host reports flavor 'mac' or 'win'; CI runners shared between Linux and macOS jobs with a shared flag list.

Related errors

• --enable-v8windbg is incompatible with --without-bundled-v8.
• Only one of the --v8-enable-object-print or --v8-disable-obj
• Only one of the --v8-enable-temporal-support or --v8-disable
• Unsupported libffi target {os_name}/{target_arch}.
• Unsupported host platform {sys.platform!r}

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