What causes "no cargo executable found at `{}`" in rust-lang/rust?

Run 'x.py clean' to remove the partial build directory, then re-run to trigger a fresh stage0 download.

rust-lang/rust · critical · Exception

no cargo executable found at `{}`

Error message

no cargo executable found at `{}`

What it means

Raised by build_bootstrap() in bootstrap.py at line 1149-1150 when the resolved cargo executable path does not exist as a regular file. The path comes from self.cargo() (program_config), which returns either the 'build.cargo' toml value (expanded) or bin_root/bin/cargo(+.exe). Before invoking cargo to build the Rust bootstrap crate, the code verifies the binary exists.

Source

Thrown at src/bootstrap/bootstrap.py:1150

        # If any of RUSTFLAGS or RUSTFLAGS_BOOTSTRAP are present and nonempty,
        # we allow arbitrary compiler flags in there, including unstable ones
        # such as `-Zthreads=8`.
        #
        # But if there aren't custom flags being passed to bootstrap, then we
        # cancel the RUSTC_BOOTSTRAP=1 from above by passing `-Zallow-features=`
        # to ensure unstable language or library features do not accidentally
        # get introduced into bootstrap over time. Distros rely on being able to
        # compile bootstrap with a variety of their toolchains, not necessarily
        # the same as Rust's CI uses.
        if env.get("RUSTFLAGS", "") or env.get("RUSTFLAGS_BOOTSTRAP", ""):
            # Preserve existing RUSTFLAGS.
            env.setdefault("RUSTFLAGS", "")
        else:
            env["RUSTFLAGS"] = "-Zallow-features="

        if not os.path.isfile(self.cargo()):
            raise Exception("no cargo executable found at `{}`".format(self.cargo()))
        args = [
            self.cargo(),
            "build",
            "--jobs=" + self.jobs,
            "--manifest-path",
            os.path.join(self.rust_root, "src/bootstrap/Cargo.toml"),
            "-Zroot-dir=" + self.rust_root,
        ]
        # verbose cargo output is very noisy, so only enable it with -vv
        args.extend("--verbose" for _ in range(self.verbose - 1))
        if self.verbose < 0:
            args.append("--quiet")

        target_features = []
        if self.get_toml("crt-static", build_section) == "true":
            target_features += ["+crt-static"]
        elif self.get_toml("crt-static", build_section) == "false":
            target_features += ["-crt-static"]

View on GitHub (pinned to 7088e4b63a)

Solutions

Run 'x.py clean' to remove the partial build directory, then re-run to trigger a fresh stage0 download.
If build.cargo is set in config.toml, verify the path exists and is executable: 'ls -la <path>'.
Check that the stage0 download step completed successfully (look for earlier 'failed verification' or download errors).
On Windows, ensure the path includes the .exe suffix or that program_config resolves it correctly via EXE_SUFFIX.

Example fix

# before: config.toml points at non-existent cargo
[build]
cargo = "/wrong/path/cargo"
# after: remove the override to use stage0 cargo, or fix the path
# (delete the line) or
cargo = "/home/user/.cargo/bin/cargo"

Defensive patterns

Strategy: validation

Validate before calling

# Before build_bootstrap, verify cargo exists
import os
def check_cargo(build):
    cargo_path = build.cargo()
    if not os.path.isfile(cargo_path):
        print(f'ERROR: cargo not found at {cargo_path}')
        print('Run x.py clean and retry to re-download stage0.')
        return False
    return True

Try / catch

try:
    build.build_bootstrap()
except Exception as e:
    if 'no cargo executable found' in str(e):
        # stage0 incomplete — clean and retry
        print('Stage0 cargo missing. Cleaning build dir and retrying...')
        # user should run: x.py clean
    raise

Prevention

Run 'x.py clean' after interrupted builds to ensure a complete stage0 re-download.
If setting build.cargo in config.toml, verify the path with 'ls -la' first.
On Windows, ensure EXE_SUFFIX handling resolves cargo.exe correctly.
Don't manually delete files from build_dir/stage0/bin/ — use x.py clean.

When it happens

Trigger: build_bootstrap() at line 1149: os.path.isfile(self.cargo()) returns False. self.cargo() resolves to either a user-configured build.cargo path in config.toml or the stage0-installed cargo under build_dir/<host>/stage0/bin/cargo. If the stage0 download/extraction failed silently, or build.cargo points to a non-existent path, this guard fires.

Common situations: The stage0 cargo was never downloaded (network failure upstream that didn't raise), an interrupted build left the bin_root incomplete, build.cargo in config.toml is set to a wrong path, EXE_SUFFIX mismatch on Windows (cargo vs cargo.exe), or the build directory was manually deleted/partially cleaned.

Related errors

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