nodejs/node · error · GypError

Invalid config specified via --build: %s

Error message

Invalid config specified via --build: %s

What it means

During the --build path (gyp actually drives a build, not just project generation), gyp raises GypError('Invalid config specified via --build: %s') when a configuration name passed via --build-configs/options.configs is not present in the first target's 'configurations' dict. valid_configs is taken from targets[flat_list[0]]['configurations'], so the check is anchored at the first build target's declared configs (e.g. 'Debug'/'Release').

Source

Thrown at tools/gyp/pylib/gyp/__init__.py:685

            params,
            options.check,
            options.circular_check,
        )

        # TODO(mark): Pass |data| for now because the generator needs a list of
        # build files that came in.  In the future, maybe it should just accept
        # a list, and not the whole data dict.
        # NOTE: flat_list is the flattened dependency graph specifying the order
        # that targets may be built.  Build systems that operate serially or that
        # need to have dependencies defined before dependents reference them should
        # generate targets in the order specified in flat_list.
        generator.GenerateOutput(flat_list, targets, data, params)

        if options.configs:
            valid_configs = targets[flat_list[0]]["configurations"]
            for conf in options.configs:
                if conf not in valid_configs:
                    raise GypError("Invalid config specified via --build: %s" % conf)
            generator.PerformBuild(data, options.configs, params)

    # Done
    return 0


def main(args):
    try:
        return gyp_main(args)
    except GypError as e:
        sys.stderr.write("gyp: %s\n" % e)
        return 1


# NOTE: console_scripts calls this function with no arguments
def script_main():
    return main(sys.argv[1:])

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Open the target's .gyp and use a configuration name that appears in its 'configurations' keys.
2. Add the missing configuration (e.g. 'Debug') to the target's configurations dict.
3. Drop the --build config argument to use the default configuration.

Example fix

# before: .gyp defines only 'Release'
python gyp --build=Debug project.gyp

# after
python gyp --build=Release project.gyp

def check_config_in_target(target_dict, config):
    valid = set(target_dict.get('configurations', {}).keys())
    if config not in valid:
        raise ValueError('--build config %r not in %s' % (config, sorted(valid)))
    return config

def config_is_valid(target_dict, config: str) -> bool:
    return config in target_dict.get('configurations', {})

try:
    gyp_main(args)
except GypError as e:
    if 'Invalid config' in str(e):
        # pick the first declared config as a safe default
        args = [a for a in args if not a.startswith('--build=')] + ['--build=<first-config>']
        raise

When it happens

Trigger: Running `gyp --build=Debug` when the target's .gyp only defines 'Release'; passing a config name with a typo; mixing configs across targets where the first target doesn't define the requested one.

Common situations: Renaming configurations in a .gyp without updating CI invocations; inheriting a gyp invocation from another project whose configs differ.

Related errors

• Not enough arguments
• `${baseKey}` is not a valid npm option
• --depfile requires --stamp and vice versa
• --depfile requires --stamp and vice versa
• Only relative paths are supported in includes

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