nodejs/node · error · GypError

The 'run_as' in target %s from file %s should be a dictionar

Error message

The 'run_as' in target %s from file %s should be a dictionary.

What it means

ValidateRunAsInTarget requires that, when present, the 'run_as' key of a target be a dict mapping fields like 'action'/'working_directory'/'environment'. A non-dict (typically a list or string) is rejected before any field is read, because the subsequent .get() calls would fail or misbehave.

Source

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

        for source_key in source_keys:
            for source in target_dict.get(source_key, []):
                (_source_root, source_extension) = os.path.splitext(source)
                if source_extension.startswith("."):
                    source_extension = source_extension[1:]
                if source_extension == rule_extension:
                    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 "

View on GitHub (pinned to 1b2de5e052)

Solutions

Wrap the run_as value in a dict.
Put the command under an 'action' key inside that dict.
Re-run gyp.

Example fix

// before
'run_as': ['my_app', '--flag'],
// after
'run_as': { 'action': ['my_app', '--flag'] },

Defensive patterns

Strategy: type-guard

Validate before calling

ra = target_dict.get('run_as')
if ra is not None and not isinstance(ra, dict):
    raise TypeError('run_as must be a dict')

Type guard

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

Prevention

Model run_as as a dict with action/working_directory/environment keys only.
Do not reuse the 'actions' list shape for run_as.
Validate .gyp files with a JSON-schema-like check before invoking gyp.

When it happens

Trigger: target_dict['run_as'] is truthy but isinstance(run_as, dict) is False.

Common situations: Writing run_as as a bare command string or as a list mimicking 'action' directly, instead of wrapping it in a dict; copy-paste from an 'actions' entry where the list form is valid.

Related errors

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