FuelLabs/sway · error · anyhow::Error

Could not find Sway repo root directory

Error message

Could not find Sway repo root directory

What it means

The mdbook-forc-documenter preprocessor locates the sway repo by walking up from the current working directory until it finds a directory that simultaneously contains Cargo.toml, forc-plugins/, and scripts/mdbook-forc-documenter/. This anyhow error is returned when the walk reaches the filesystem root (Path::parent() returns None) without ever matching those three markers. The error propagates through find_forc_cmd_examples_dir and load_examples (which unwraps it), aborting book builds that need the forc command examples directory.

Source

Thrown at scripts/mdbook-forc-documenter/src/lib.rs:173

fn find_sway_repo_root() -> anyhow::Result<PathBuf> {
    let mut curr_path = std::env::current_dir().unwrap();
    loop {
        if curr_path.is_dir() {
            // Some heuristics that should pass if we've found the sway repo.
            if curr_path.join("Cargo.toml").exists()
                && curr_path.join("forc-plugins").exists()
                && curr_path
                    .join("scripts")
                    .join("mdbook-forc-documenter")
                    .exists()
            {
                return Ok(curr_path);
            }
        }
        curr_path = curr_path
            .parent()
            .ok_or_else(|| anyhow!("Could not find Sway repo root directory"))?
            .to_path_buf();
    }
}

fn find_forc_cmd_examples_dir() -> anyhow::Result<PathBuf> {
    let sway_dir = find_sway_repo_root()?;
    let examples_dir = sway_dir
        .join("scripts")
        .join("mdbook-forc-documenter")
        .join("examples");
    if !examples_dir.exists() || !examples_dir.is_dir() {
        bail!(
            "Failed to find examples directory at {}",
            examples_dir.display()
        );
    }
    Ok(examples_dir)
}

View on GitHub (pinned to 47e5e902fa)

Solutions

1. Run the book build from inside the sway repo, e.g. `cd ~/sway && mdbook build docs/book`, so the upward walk from docs/book hits the repo root.
2. Verify the three markers exist at the expected root: Cargo.toml, forc-plugins/, scripts/mdbook-forc-documenter/ — restore any that were moved or renamed.
3. If the repo layout legitimately changed, update the heuristic in find_sway_repo_root (scripts/mdbook-forc-documenter/src/lib.rs:161) to the new markers.
4. If you only need plain docs without example injection, remove the preprocessor from docs/book.toml.

Example fix

// before
$ cd ~ && mdbook build ~/sway/docs/book   # cwd outside repo -> error
// after
$ cd ~/sway && mdbook build docs/book        # walk from docs/book finds repo root

# run before mdbook build: confirm cwd is inside the sway repo
walk=$(pwd)
while [ "$walk" != "/" ]; do
  [ -f "$walk/Cargo.toml" ] && [ -d "$walk/forc-plugins" ] && [ -d "$walk/scripts/mdbook-forc-documenter" ] && break
  walk=$(dirname "$walk")
done
[ "$walk" != "/" ] || { echo "run from inside the sway repo" >&2; exit 1; }

When it happens

Trigger: Invoking mdbook or the preprocessor binary with a working directory outside the sway checkout; running an installed copy of mdbook-forc-documenter from $HOME or another project; the repo layout changing so scripts/mdbook-forc-documenter no longer exists next to Cargo.toml and forc-plugins; std::env::current_dir() resolving into a directory tree that never contains all three markers.

Common situations: Building the forc book locally from the wrong shell/directory; cargo-installing the preprocessor and running it like a normal binary; CI checkouts that only fetch docs/ without the rest of the repo; renaming or moving the scripts directory during refactors.

Related errors

• Failed to run forc plugins
• Source file was modified, and the mapping is now out of rang
• InvalidData
• Could not get homedir
• The allocator cannot resolve a register mapping for this pro

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