nodejs/node · error · Exception

gn gen failed

Error message

gn gen failed

What it means

update-compile-commands.py's PrepareBuildDir() sets up an out/<arch>.<mode> build directory and runs `gn gen` to generate ninja files. If `gn gen <build_dir>` exits with a non-zero code (missing gn binary, bad args.gn, GN syntax error, or a stale build dir), it raises a plain Exception("gn gen failed"). The error message carries no gn output, so the real cause is only visible in the printed _Call output.

Source

Thrown at deps/v8/tools/dev/update-compile-commands.py:61

  return subprocess.call(cmd, shell=True)

def _Write(filename, content):
  with open(filename, "w") as f:
    f.write(content)

def PrepareBuildDir(arch, mode):
  build_dir = os.path.join("out", f"{arch}.{mode}")
  if not os.path.exists(build_dir):
    print(f"# mkdir -p {build_dir}")
    os.makedirs(build_dir)
  args_gn = os.path.join(build_dir, "args.gn")
  if not os.path.exists(args_gn):
    conf = gm.ManagedConfig(arch, mode, [])
    _Write(args_gn, conf.get_gn_args())
  build_ninja = os.path.join(build_dir, "build.ninja")
  if not os.path.exists(build_ninja):
    code = _Call(f"gn gen {build_dir}")
    if code != 0: raise Exception("gn gen failed")
  else:
    _Call(f"autoninja -C {build_dir} build.ninja")
  return build_dir

def AddTargetsForArch(arch, combined):
  build_dir = PrepareBuildDir(arch, "debug")
  commands = compile_db.ProcessCompileDatabase(
                compile_db.GenerateWithNinja(build_dir, ["all"]), [])
  added = 0
  for c in commands:
    key = c["file"]
    if key not in combined:
      combined[key] = c
      added += 1
  print(f"{arch}: added {added} compile commands")

def UpdateCompileCommands():
  print(">>> Updating compile_commands.json...")

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Run `gn gen out/<arch>.debug` manually in the repo root to see the full GN error output, then fix the reported cause.
2. Ensure depot_tools is on PATH so the `gn` wrapper resolves (`which gn`).
3. Delete the offending out/<arch>.<mode> directory and let PrepareBuildDir regenerate args.gn from a clean state.
4. Validate the args.gn contents (is_component_build, target_cpu, v8_target_cpu, is_debug) against the current V8 GN schema.

Example fix

// before
    code = _Call(f"gn gen {build_dir}")
    if code != 0: raise Exception("gn gen failed")
// after
    code = _Call(f"gn gen {build_dir}")
    if code != 0:
      raise Exception(f"gn gen failed (exit {code}) for {build_dir}; see output above")

import shutil, subprocess
if not shutil.which('gn'):
    sys.exit('gn not on PATH; add depot_tools first.')
rc = subprocess.call(['gn', 'gen', build_dir])
if rc != 0:
    sys.exit(f'gn gen failed (exit {rc}); rerun manually for full diagnostics')

null

null

When it happens

Trigger: Calling AddTargetsForArch / PrepareBuildDir when `gn` is not on PATH, when the generated args.gn contains an invalid flag, when the out/<arch>.<mode> dir is partially initialized, or when gn itself errors (e.g. target CPU unsupported). The check is `code = _Call(...); if code != 0: raise`.

Common situations: First-time V8 checkout where gn (from depot_tools) is not yet on PATH; a stale out/ dir left over from a branch switch; an args.gn referencing a removed GN arg after a V8 upgrade; running outside depot_tools so `gn` is unresolved.

Related errors

• Phase %s doesn't exist for %s on %s
• Must not specify a build --phase for %s on %s
• args_file specified multiple times in mixins for %s on %s
• Missing property '%s'. If you see this error in testing, yo
• --depfile requires --stamp and vice versa

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