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.

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)

Solutions

1. Update the toolchain so `forc plugins` succeeds in the same shell: `fuelup update && fuelup default latest`.
2. Verify before building: `which forc && forc plugins` must list plugins with exit code 0.
3. 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

# 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; }

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

• Could not get plugin description.
• Could not get plugin info: {}
• Could not find Sway repo root directory
• Source file was modified, and the mapping is now out of rang
• failed to parse manifest: {}.

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