nodejs/node · error · GypError

The 'action' for 'run_as' in target %s from file %s must be

Error message

The 'action' for 'run_as' in target %s from file %s must be a list.

What it means

run_as.action must be a list of command arguments (argv form). A scalar string or dict is rejected so that gyp can pass the list straight through to the spawned process without splitting logic.

Source

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

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 "
            "in file %s should be a dictionary." % (target_name, build_file)
        )


def ValidateActionsInTarget(target, target_dict, build_file):

View on GitHub (pinned to 1b2de5e052)

Solutions

Convert the action value into a list where each element is one argument.
Ensure the program path and each flag are separate list entries.
Re-run gyp.

Example fix

// before
'run_as': { 'action': '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 isinstance(ra, dict):
    a = ra.get('action')
    if a is not None and not isinstance(a, list):
        raise TypeError('run_as.action must be a list')

Type guard

def run_as_action_is_list(target_dict: dict) -> bool:
    ra = target_dict.get('run_as')
    if not isinstance(ra, dict):
        return True
    a = ra.get('action')
    return a is None or isinstance(a, list)

Prevention

Use argv list form ['prog', '--flag'] for action, never a shell string.
Keep a shared lint helper that asserts run_as.action is a list.

When it happens

Trigger: run_as['action'] is present and truthy but isinstance(action, list) is False (e.g. a single string).

Common situations: Writing 'action': 'my_app --flag' as a shell-style string instead of an argv list; migrating from a format that used strings.

Related errors

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