nodejs/node · error · Exception

Must specify files to analyze via config_path generator flag

Error message

Must specify files to analyze via config_path generator flag

What it means

Thrown by the analyzer generator's GenerateOutput when the loaded config has no 'files' entry (or an empty one). The analyzer exists to determine which targets are affected by a set of changed files, so an empty file list is a fatal misuse rather than a no-op. It indicates the config_path file is structurally valid but missing the essential 'files' key.

Source

Thrown at tools/gyp/pylib/gyp/generator/analyzer.py:750

        print("Supplied test_targets & compile_targets")
        for target in supplied_targets:
            print("\t", target.name)
        print("Finding compile targets")
        compile_targets = _GetCompileTargets(self._changed_targets, supplied_targets)
        return [
            gyp.common.ParseQualifiedTarget(target.name)[1]
            for target in compile_targets
        ]


def GenerateOutput(target_list, target_dicts, data, params):
    """Called by gyp as the final stage. Outputs results."""
    config = Config()
    try:
        config.Init(params)

        if not config.files:
            raise Exception(
                "Must specify files to analyze via config_path generator flag"
            )

        toplevel_dir = _ToGypPath(os.path.abspath(params["options"].toplevel_dir))
        if debug:
            print("toplevel_dir", toplevel_dir)

        if _WasGypIncludeFileModified(params, config.files):
            result_dict = {
                "status": all_changed_string,
                "test_targets": list(config.test_target_names),
                "compile_targets": list(
                    config.additional_compile_target_names | config.test_target_names
                ),
            }
            _WriteOutput(params, **result_dict)
            return

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Ensure the config JSON includes a non-empty "files" array listing the changed source paths.
2. If the changed-file set is genuinely empty, skip invoking the analyzer generator entirely rather than passing an empty config.
3. Check the upstream tool that populates 'files' (git diff, etc.) actually produced output.

Example fix

// before
{
  "test_targets": ["foo"],
  "additional_compile_targets": []
}
// after
{
  "files": ["src/foo.cc"],
  "test_targets": ["foo"],
  "additional_compile_targets": []
}

import json
with open('config.json') as f:
    cfg = json.load(f)
files = cfg.get('files', [])
if not files:
    raise SystemExit('config must contain a non-empty "files" array')

def has_nonempty_files(cfg) -> bool:
    return isinstance(cfg, dict) and isinstance(cfg.get('files'), list) and len(cfg['files']) > 0

try:
    GenerateOutput(target_list, target_dicts, data, params)
except Exception as e:
    if 'Must specify files to analyze' in str(e):
        skip_analyzer_run()
    raise

When it happens

Trigger: Calling gyp with the analyzer generator where the config JSON parses and is a dict, but either lacks a 'files' key or 'files' maps to an empty list. config.files defaults to [] via config.get('files', []) and the `if not config.files` check at analyzer.py:752 fires.

Common situations: Omitting the 'files' key in the config; an upstream tool that computes the changed-file list produced an empty set (e.g. a CI step with no diff); typo'd key like 'file' instead of 'files'.

Related errors

• Unable to open file %s
• Unable to parse config file %s%s
• config_path must be a JSON file containing a dictionary
• GYP_MSVS_OVERRIDE_PATH requires GYP_MSVS_VERSION to be set t
• %s: error: no build_file

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