What causes "Failed to spawn rustdoc: {}" in rust-lang/rust?

Run `rustup toolchain list` and `rustup component add rust-docs --toolchain ` for the expected toolchain.

Failed to spawn rustdoc: {}

Error message

Failed to spawn rustdoc: {}

What it means

Panics in the rustdoc-clif launcher shim when Command::exec() cannot replace the process with rustdoc. Identical shape to rustc-clif (error 63) but for the documentation driver; rustdoc-clif injects the cranelift backend and sysroot and then execs rustdoc.

Source

Thrown at compiler/rustc_codegen_cranelift/scripts/rustdoc-clif.rs:54

        args.push(OsString::from(sysroot.to_str().unwrap()));
    }
    if passed_args.is_empty() {
        // Don't pass any arguments when the user didn't pass any arguments
        // either to ensure the help message is shown.
        args.clear();
    }
    args.extend(passed_args);

    let rustdoc = if let Some(rustdoc) = option_env!("RUSTDOC") {
        rustdoc
    } else {
        // Ensure that the right toolchain is used
        env::set_var("RUSTUP_TOOLCHAIN", option_env!("TOOLCHAIN_NAME").expect("TOOLCHAIN_NAME"));
        "rustdoc"
    };

    #[cfg(unix)]
    panic!("Failed to spawn rustdoc: {}", Command::new(rustdoc).args(args).exec());

    #[cfg(not(unix))]
    std::process::exit(
        Command::new(rustdoc).args(args).spawn().unwrap().wait().unwrap().code().unwrap_or(1),
    );
}

View on GitHub (pinned to 22057b88b0)

Solutions

Run `rustup toolchain list` and `rustup component add rust-docs --toolchain <toolchain>` for the expected toolchain.
Run `which rustdoc` / `$RUSTDOC --version` to confirm the binary is executable.
Invoke via `rustup run <toolchain> rustdoc-clif` so the component paths resolve.
Re-run `./y.rs prepare` to repair the toolchain install.

Example fix

// before
#[cfg(unix)]
panic!("Failed to spawn rustdoc: {}", Command::new(rustdoc).args(args).exec());
// after
#[cfg(unix)]
{
    eprintln!("rustdoc-clif: exec rustdoc={:?} sysroot={:?}", rustdoc, sysroot);
    panic!("Failed to spawn rustdoc: {}", Command::new(rustdoc).args(args).exec());
}

Defensive patterns

Strategy: validation

Validate before calling

fn ensure_tool(name: &str) -> Result<(), String> {
    if which::which(name).is_err() {
        return Err(format!("{} not found on PATH; run `rustup component add rust-docs` or install rustdoc", name));
    }
    Ok(())
}
// call ensure_tool("rustdoc") before invoking rustdoc-clif

Type guard

fn rustdoc_available() -> bool {
    std::process::Command::new("rustdoc").arg("--version").status().is_ok()
}

Try / catch

use std::panic;
if panic::catch_unwind(|| Command::new("rustdoc").args(args).status()).is_err() {
    eprintln!("rustdoc spawn failed; install rust-docs / fix PATH"); std::process::exit(1);
}

Prevention

Check `rustdoc --version` exists; it ships with rustc but can be omitted in minimal installs.
Ensure the same toolchain that provides rustc also provides rustdoc on PATH.
Avoid invoking rustdoc-clif from environments where the docs component is not installed.
Validate PATH is intact (e.g. login shells, CI images) before doc builds.

When it happens

Trigger: Reached at the tail of rustdoc-clif.rs (unix path) when exec of the assembled rustdoc Command fails. Only the exec syscall failure panics; rustdoc's own errors propagate via its exit code.

Common situations: rustdoc missing from the toolchain or RUSTDOC env var pointing at a bad path; rustup toolchain named by TOOLCHAIN_NAME not installed; running `cargo doc` via cargo-clif in a container where the docs component (`rust-docs` / `rust-src`) was omitted; relocation of the binary so the computed sysroot is wrong.

Related errors

AI-assisted analysis of rust-lang/rust@22057b88b0 (2026-08-03). Data as JSON: /data/errors/3ca1799f6f60d0f1.json. Report an issue: GitHub.