FuelLabs/fuels-rs · error

could not canonicalize md path

Error message

could not canonicalize md path

What it means

check-docs (the docs CI helper) collects markdown files found under src and canonicalizes each path to compare it against the files referenced in SUMMARY.md. The expect fires when canonicalize fails: the path does not exist (deleted/renamed file, typo, dangling symlink) or a parent directory is unreadable.

Source

Thrown at scripts/check-docs/src/lib.rs:222

        .filter_map(|line| regex.captures(line))
        .map(|capture| {
            let path = PathBuf::from(path).join(&capture[1]);
            path.canonicalize()
                .unwrap_or_else(|e| panic!("could not canonicalize md path: {e} {path:?}"))
        })
        .collect()
}

pub fn validate_md_files(
    md_files_summary: HashSet<PathBuf>,
    md_files_in_src: String,
) -> Vec<Error> {
    md_files_in_src
        .lines()
        .filter_map(|file| {
            let file = PathBuf::from(file)
                .canonicalize()
                .expect("could not canonicalize md path");

            (!md_files_summary.contains(&file))
                .then(|| anyhow!("file `{}` not in SUMMARY.md", file.to_str().unwrap()))
        })
        .collect()
}

pub fn search_for_pattern(pattern: &str, location: &str) -> anyhow::Result<String> {
    let grep_project = std::process::Command::new("grep")
        .arg("-H") // print filename
        .arg("-n") // print line-number
        .arg("-r") // search recursively
        .arg("--binary-files=without-match")
        .arg("--exclude-dir=check-docs")
        .arg(pattern)
        .arg(location)
        .output()
        .expect("failed grep command");

View on GitHub (pinned to d9a250a518)

Solutions

1. Check the failing path exists (ls) and fix the rename/typo
2. Fix or remove dangling symlinks under src
3. Run the script from the repository root the same way CI does

// Check the listing before comparing against SUMMARY.md
for p in md_files_in_src.lines() {
    let path = std::path::PathBuf::from(p);
    if !path.exists() {
        eprintln!("missing md file: {p}");
    }
}

When it happens

Trigger: A .md path returned by the file listing that cannot be canonicalized: files moved or deleted between listing and validation, broken symlinks inside src, or running the script from a working directory where the relative paths do not resolve.

Common situations: Docs CI after renaming markdown files; symlinks in monorepos; running the script manually from a subdirectory instead of the repo root.

Related errors

• failed grep command
• Program `find` not in PATH
• No anchor available to satisfy include {include:?}
• Anchor unused: {unused_anchor:?}!
• {the_path:?} when canonicalized gives error {err:?}\ninclude

AI-assisted analysis of FuelLabs/fuels-rs@d9a250a518 (2026-08-16). Data as JSON: /api/errors/892c0dbe25cec27e. Report an issue: GitHub.