What causes "Failed to run forc plugins" in FuelLabs/sway?

Update the toolchain so `forc plugins` succeeds in the same shell: `fuelup update && fuelup default latest`.

FuelLabs/sway · error · anyhow::Error

Failed to run forc plugins

Error message

Failed to run forc plugins

What it means

To document installed plugins, the preprocessor shells out to `forc plugins` and parses lines containing "forc-". After the child process runs, this anyhow error is returned when the process exits with a non-zero status. (A missing/unspawnable forc binary is a different failure: the .expect("Failed running forc plugins") panic just above.) As the doc comment notes, discovery is only reliable in Sway CI where the plugin set is controlled.

Solutions

Update the toolchain so `forc plugins` succeeds in the same shell: `fuelup update && fuelup default latest`.
Verify before building: `which forc && forc plugins` must list plugins with exit code 0.
If you must keep an old forc, install a newer one side-by-side and prepend its bin dir to PATH only for the mdbook build.

Example fix

// before
$ forc plugins
error: unrecognized subcommand 'plugins'  -> preprocessor fails
// after
$ fuelup update && forc plugins
forc-alerts, forc-explore, forc-fmt, forc-lsp, forc-tx  -> docs build proceeds

Defensive patterns

Strategy: validation

Validate before calling

# before building docs, require a forc that supports `plugins`
command -v forc >/dev/null 2>&1 || { echo "forc not on PATH" >&2; exit 1; }
forc plugins >/dev/null 2>&1 || { echo "forc plugins failed; run fuelup update" >&2; exit 1; }

Prevention

Pin the fuelup toolchain in CI and update before docs jobs.
Smoke-test `forc plugins` in the same shell/environment that runs mdbook.
Check `which forc` resolves to the fuelup-managed binary, not a stale copy.

When it happens

Trigger: Running the docs build with an old forc on PATH that predates the `plugins` subcommand (unknown subcommand -> non-zero exit); a shell alias/wrapper named forc that fails; a corrupted fuelup-managed forc that exits non-zero; PATH pointing at a forc binary from an incompatible toolchain.

Common situations: Building the book on a developer machine whose fuelup default toolchain is outdated; CI images where forc was installed manually at an old version; local PATH ordering picking up a broken binary before the fuelup one.

Related errors

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

Appendix: source

Thrown at scripts/mdbook-forc-documenter/src/plugins.rs:16

use anyhow::{anyhow, Result};
use std::{collections::HashSet, process};

/// Detects plugins available via `PATH`.
///
/// Note that plugin discovery works reliably within the Sway CI since the installed plugins are in
/// a controlled environment. Building the book locally on your own machine may create a different
/// book depending on what plugins are available on your PATH.
pub(crate) fn forc_plugins_from_path() -> Result<Vec<String>> {
    let output = process::Command::new("forc")
        .arg("plugins")
        .output()
        .expect("Failed running forc plugins");

    if !output.status.success() {
        return Err(anyhow!("Failed to run forc plugins"));
    }

    let mut plugins = HashSet::new();
    let s = String::from_utf8_lossy(&output.stdout) + String::from_utf8_lossy(&output.stderr);

    for plugin in s.lines() {
        if let Some(("", command)) = plugin.split_once("forc-") {
            plugins.insert(command.to_string());
        }
    }

    Ok(Vec::from_iter(plugins))
}

View on GitHub (pinned to 47e5e902fa)