nodejs/node · error · Exception

--enable-v8windbg is incompatible with --without-bundled-v8.

Error message

--enable-v8windbg is incompatible with --without-bundled-v8.

What it means

Node.js's configure.py rejects combining --enable-v8windbg with --without-bundled-v8. The v8windbg Visual Studio debugger extension needs the V8 sources that ship inside the Node tree (node_use_bundled_v8). With --without-bundled-v8, V8 is pulled in as an external prebuilt library via pkg_config("v8"), so the debugger source files it would compile against no longer exist in the build.

Source

Thrown at configure.py:2244

        options.v8_disable_temporal_support = True
      case 'system-icu':
        warn('Temporal support disabled when compiling with a shared ICU library')
        options.v8_disable_temporal_support = True
  o['variables']['v8_enable_temporal_support'] = 0 if options.v8_disable_temporal_support else 1
  o['variables']['v8_trace_maps'] = 1 if options.trace_maps else 0
  o['variables']['v8_use_perfetto'] = 1 if options.with_perfetto else 0
  o['variables']['node_use_v8_platform'] = b(not options.without_v8_platform)
  o['variables']['node_use_bundled_v8'] = b(not options.without_bundled_v8)
  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.')

View on GitHub (pinned to 1b2de5e052)

Solutions

Remove --enable-v8windbg from the configure invocation when --without-bundled-v8 is set.
If you need v8windbg, drop --without-bundled-v8 so the bundled V8 tree is built.
Audit build scripts/cmake presets that template both flags together and gate v8windbg on the platform/build mode.

Example fix

// before
./configure --without-bundled-v8 --enable-v8windbg
// after
./configure --without-bundled-v8

Defensive patterns

Strategy: validation

Validate before calling

import sys
bundled_off = '--without-bundled-v8' in sys.argv
windbg_on = '--enable-v8windbg' in sys.argv
assert not (bundled_off and windbg_on), 'enable-v8windbg needs bundled V8'

Prevention

Keep all v8-related feature flags in one section of the build script and annotate which require --without-bundled-v8 to be absent.
Run a pre-flight argv validator that knows configure.py's mutual-exclusion rules before invoking configure.

When it happens

Trigger: Invoked when options.without_bundled_v8 and options.enable_v8windbg are both truthy during configure_input / configure_node. Reached only inside the `if options.without_bundled_v8:` block, immediately after the analogous --enable-d8 guard.

Common situations: Distributions building Node against a system V8 package (Debian/Fedora) who copied a Windows-debugging flag from a build script; CI that sets --without-bundled-v8 globally and then layers feature flags on top.

Related errors

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