rust-lang/rust · critical · RuntimeError

failed to run: {args}

Error message

failed to run: {args}

What it means

Raised or sys.exit'd by run() in bootstrap.py at line 235-245 when a child process returns a non-zero exit code. If verbose > 0 or exception=True, it raises RuntimeError; otherwise it calls sys.exit with the error message (or sys.exit(1) if is_bootstrap is true, since the bootstrap binary already printed its own error). The function is the central process-execution helper for Python bootstrap.

Source

Thrown at src/bootstrap/bootstrap.py:237


def run(args, verbose=0, exception=False, is_bootstrap=False, **kwargs):
    """Run a child program in a new process"""
    if verbose > 0:
        eprint("running: " + " ".join(args))
    sys.stdout.flush()
    # Ensure that the .exe is used on Windows just in case a Linux ELF has been
    # compiled in the same directory.
    if os.name == "nt" and not args[0].endswith(".exe"):
        args[0] += ".exe"
    # Use Popen here instead of call() as it apparently allows powershell on
    # Windows to not lock up waiting for input presumably.
    ret = subprocess.Popen(args, **kwargs)
    code = ret.wait()
    if code != 0:
        err = "failed to run: " + " ".join(args)
        if verbose > 0 or exception:
            raise RuntimeError(err)
        # For most failures, we definitely do want to print this error, or the user will have no
        # idea what went wrong. But when we've successfully built bootstrap and it failed, it will
        # have already printed an error above, so there's no need to print the exact command we're
        # running.
        if is_bootstrap:
            sys.exit(1)
        else:
            sys.exit(err)


def run_powershell(script, *args, **kwargs):
    """Run a powershell script"""
    run(["PowerShell.exe", "/nologo", "-Command"] + script, *args, **kwargs)


def require(cmd, exit=True, exception=False):
    """Run a command, returning its output.
    On error,

View on GitHub (pinned to 7088e4b63a)

Solutions

  1. Re-run with increased verbosity (x.py -vv) to see the exact command and its output before the failure.
  2. Read the child process's own stderr/stdout which is printed above the 'failed to run' message.
  3. Verify all build prerequisites are installed (gcc/g++, cmake, ninja, python3, git) per https://github.com/rust-lang/rust#building-from-source.
  4. Check for disk space, memory, or file-descriptor limits that could cause the child process to fail.
  5. If building bootstrap, ensure the cargo and rustc from stage0 are functional.
Defensive patterns

Strategy: try-catch

Validate before calling

# Pre-check that the command exists before running it
import shutil, os
def command_available(cmd):
    return os.path.isfile(cmd) or shutil.which(cmd) is not None

Try / catch

try:
    run(args, verbose=verbose, exception=True)
except RuntimeError as e:
    if 'failed to run' in str(e):
        print(f'Command failed: {" ".join(args)}')
        print('Check prerequisites: gcc, cmake, ninja, python3, git.')
    raise

Prevention

When it happens

Trigger: run(args, ...) spawns the command via subprocess.Popen at line 232, waits for it at line 233, and at line 234 finds code != 0. This fires for any external command bootstrap runs that fails: building bootstrap itself via cargo, running the compiled bootstrap binary (line 1414), running curl for downloads, or any helper process. The error message includes the full argument list.

Common situations: The bootstrap cargo build fails (missing dependencies, compilation error); the compiled rust bootstrap binary crashes; curl fails to download stage0 artifacts; a required system tool (git, cmake, ninja) is missing or returns an error; or an incompatible system library breaks the build.

Related errors

AI-assisted analysis of rust-lang/rust@7088e4b63a (2026-08-10). Data as JSON: /api/errors/14fb0dfe1fb97250. Report an issue: GitHub.