nodejs/node · error · GypError

The 'run_as' in target %s from file %s must have an 'action'

Error message

The 'run_as' in target %s from file %s must have an 'action' section.

What it means

After confirming run_as is a dict, ValidateRunAsInTarget reads its 'action' field and treats a missing or empty value as invalid, because a run_as entry with nothing to execute has no purpose.

Source

Thrown at tools/gyp/pylib/gyp/input.py:2782

                    rule_sources.append(source)

        if len(rule_sources) > 0:
            rule["rule_sources"] = rule_sources


def ValidateRunAsInTarget(target, target_dict, build_file):
    target_name = target_dict.get("target_name")
    run_as = target_dict.get("run_as")
    if not run_as:
        return
    if not isinstance(run_as, dict):
        raise GypError(
            "The 'run_as' in target %s from file %s should be a "
            "dictionary." % (target_name, build_file)
        )
    action = run_as.get("action")
    if not action:
        raise GypError(
            "The 'run_as' in target %s from file %s must have an "
            "'action' section." % (target_name, build_file)
        )
    if not isinstance(action, list):
        raise GypError(
            "The 'action' for 'run_as' in target %s from file %s "
            "must be a list." % (target_name, build_file)
        )
    working_directory = run_as.get("working_directory")
    if working_directory and not isinstance(working_directory, str):
        raise GypError(
            "The 'working_directory' for 'run_as' in target %s "
            "in file %s should be a string." % (target_name, build_file)
        )
    environment = run_as.get("environment")
    if environment and not isinstance(environment, dict):
        raise GypError(
            "The 'environment' for 'run_as' in target %s "

View on GitHub (pinned to 1b2de5e052)

Solutions

Add an 'action' key to the run_as dict whose value is a non-empty list of command arguments.
Check for typos in the key name ('action' vs 'actions'/'command').
Re-run gyp.

Example fix

// before
'run_as': { 'working_directory': '<(PRODUCT_DIR)' },
// after
'run_as': { 'action': ['<(PRODUCT_DIR)/my_app'], 'working_directory': '<(PRODUCT_DIR)' },

Defensive patterns

Strategy: validation

Validate before calling

ra = target_dict.get('run_as')
if isinstance(ra, dict) and not ra.get('action'):
    raise ValueError('run_as.action is required and must be non-empty')

Type guard

def run_as_has_action(target_dict: dict) -> bool:
    ra = target_dict.get('run_as')
    return ra is None or (isinstance(ra, dict) and bool(ra.get('action')))

Prevention

Always author run_as with an 'action' key, even in early drafts.
Distinguish 'action' (run_as) from 'actions' (target-level) — different concepts.

When it happens

Trigger: target_dict['run_as'] is a dict but run_as.get('action') returns None or a falsy value (empty list/string).

Common situations: Adding run_as with only working_directory/environment set and forgetting action; renaming the key; typos like 'actions' instead of 'action'.

Related errors

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