{"record":{"id":"380d113ca889efde","repo":"FuelLabs/sway","slug":"failed-to-run-forc-help","errorCode":null,"errorMessage":"Failed to run forc {} --help","messagePattern":"Failed to run forc (.+?) --help","errorType":"console","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"scripts/mdbook-forc-documenter/src/commands.rs","lineNumber":59,"sourceCode":"        let Ok(result) = generate_documentation(command) else {\n            continue;\n        };\n        contents.insert(\"forc \".to_owned() + command, result);\n    }\n    contents\n}\n\nfn generate_documentation(subcommand: &str) -> Result<String> {\n    let mut result = String::new();\n    let mut has_parsed_subcommand_header = false;\n\n    let output = process::Command::new(\"forc\")\n        .args([subcommand, \"--help\"])\n        .output()\n        .expect(\"Failed running forc --help\");\n\n    if !output.status.success() {\n        return Err(anyhow!(\"Failed to run forc {} --help\", subcommand));\n    }\n\n    let s = String::from_utf8_lossy(&output.stdout) + String::from_utf8_lossy(&output.stderr);\n\n    for (index, line) in s.lines().enumerate() {\n        let mut formatted_line = String::new();\n        let line = line.trim();\n\n        if line == \"SUBCOMMANDS:\" {\n            has_parsed_subcommand_header = true;\n        }\n\n        if index == 0 {\n            formatted_line.push_str(&format_header_line(line));\n        } else if index == 1 {\n            formatted_line.push_str(line);\n        } else {\n            formatted_line.push_str(&format_line(line, has_parsed_subcommand_header));","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/FuelLabs/sway/blob/47e5e902faa42baf652dd6a0c88cd23390c1a614/scripts/mdbook-forc-documenter/src/commands.rs#L41-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Verify the exact binary used: `which forc` and `forc <subcommand> --help` manually; fix whatever makes it fail","Reinstall/align the toolchain (fuelup update / cargo install --locked forc) so every documented subcommand's --help succeeds","In CI, pin the forc version to one matching the documentation being built"],"exampleFix":"# before\nforc addr2line --help   # exits non-zero, doc build fails\n\n# after\nfuelup update && forc addr2line --help && mdbook build","handlingStrategy":"validation","validationCode":"// Pre-flight every subcommand you document, mirroring the documenter.\nfor sub in [\"build\", \"test\", \"addr2line\"] {\n    let st = std::process::Command::new(\"forc\").args([sub, \"--help\"]).status()?;\n    anyhow::ensure!(st.success(), \"forc {sub} --help failed; fix the forc installation first\");\n}","typeGuard":null,"tryCatchPattern":"let output = std::process::Command::new(\"forc\").args([subcommand, \"--help\"]).output()?;\nif !output.status.success() {\n    let err = String::from_utf8_lossy(&output.stderr);\n    anyhow::bail!(\"forc {subcommand} --help failed: {err} — reinstall forc (fuelup update) and retry\");\n}","preventionTips":["Pin the forc version in docs CI to match the toolchain that built the book","Verify `forc --version` and each subcommand's `--help` in a smoke-test job before generating documentation"],"tags":["mdbook","documentation","forc","cli","process-exit"],"backgroundTag":null,"analyzedSha":"47e5e902faa42baf652dd6a0c88cd23390c1a614","analyzedAt":"2026-08-16T07:57:45.555Z","schemaVersion":2},"datasetVersion":"2026-08-16T08:17:34.114Z"}