FuelLabs/sway · error · anyhow::Error

Failed to run forc {} --help

Error message

Failed to run forc {} --help

What it means

mdbook-forc-documenter generates the CLI reference by running `forc <subcommand> --help` and capturing output. If the child process runs but exits with a non-zero status, it returns Err(anyhow!("Failed to run forc <sub> --help")). Note the preceding .expect panics if the forc binary cannot be spawned at all — this error is specifically about a non-success exit status.

Source

Thrown at scripts/mdbook-forc-documenter/src/commands.rs:59

        let Ok(result) = generate_documentation(command) else {
            continue;
        };
        contents.insert("forc ".to_owned() + command, result);
    }
    contents
}

fn generate_documentation(subcommand: &str) -> Result<String> {
    let mut result = String::new();
    let mut has_parsed_subcommand_header = false;

    let output = process::Command::new("forc")
        .args([subcommand, "--help"])
        .output()
        .expect("Failed running forc --help");

    if !output.status.success() {
        return Err(anyhow!("Failed to run forc {} --help", subcommand));
    }

    let s = String::from_utf8_lossy(&output.stdout) + String::from_utf8_lossy(&output.stderr);

    for (index, line) in s.lines().enumerate() {
        let mut formatted_line = String::new();
        let line = line.trim();

        if line == "SUBCOMMANDS:" {
            has_parsed_subcommand_header = true;
        }

        if index == 0 {
            formatted_line.push_str(&format_header_line(line));
        } else if index == 1 {
            formatted_line.push_str(line);
        } else {
            formatted_line.push_str(&format_line(line, has_parsed_subcommand_header));

View on GitHub (pinned to 47e5e902fa)

Solutions

1. Verify the exact binary used: `which forc` and `forc <subcommand> --help` manually; fix whatever makes it fail
2. Reinstall/align the toolchain (fuelup update / cargo install --locked forc) so every documented subcommand's --help succeeds
3. In CI, pin the forc version to one matching the documentation being built

Example fix

# before
forc addr2line --help   # exits non-zero, doc build fails

# after
fuelup update && forc addr2line --help && mdbook build

// Pre-flight every subcommand you document, mirroring the documenter.
for sub in ["build", "test", "addr2line"] {
    let st = std::process::Command::new("forc").args([sub, "--help"]).status()?;
    anyhow::ensure!(st.success(), "forc {sub} --help failed; fix the forc installation first");
}

let output = std::process::Command::new("forc").args([subcommand, "--help"]).output()?;
if !output.status.success() {
    let err = String::from_utf8_lossy(&output.stderr);
    anyhow::bail!("forc {subcommand} --help failed: {err} — reinstall forc (fuelup update) and retry");
}

When it happens

Trigger: Running the documentation build (scripts/mdbook-forc-documenter) with a broken or incompatible `forc` on PATH: one that parses args but fails during --help, e.g. a forc whose subcommand panics, a plugin-style subcommand crashing, or version drift where a documented subcommand no longer exists.

Common situations: Docs CI picking up a different forc (old fuelup toolchain, stale PATH order), half-completed forc installs, or a subcommand that errors before printing help.

Related errors

• missing dependency name
• invalid version requirement `{v}`
• Invalid salt format: {}
• the dependency `{}` could not be found in `{}`
• failed to read manifest at {:?}: {}

AI-assisted analysis of FuelLabs/sway@47e5e902fa (2026-08-16). Data as JSON: /api/errors/380d113ca889efde. Report an issue: GitHub.