FuelLabs/fuels-rs · error · anyhow::Error

{the_path:?} when canonicalized gives error {err:?}\ninclude

Error message

{the_path:?} when canonicalized gives error {err:?}\ninclude_file: {:?}

What it means

Doc-checking error (scripts/check-docs): while parsing an include directive, the anchor target file path could not be canonicalized. Canonicalization fails when the path does not exist on disk, so this means the anchor-file part of the include points to a non-existent file. The message includes the offending path and the underlying io error kind.

Source

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

    pub include_file: PathBuf,
    pub line_no: usize,
}

pub fn parse_includes(text_w_includes: String) -> (Vec<Include>, Vec<Error>) {
    let apply_regex = |regex: Regex| {
        let (includes, errors): (Vec<_>, Vec<_>) = text_w_includes
            .lines()
            .filter_map(|line| regex.captures(line))
            .map(|capture| {
                let include_file = PathBuf::from(&capture[1]).canonicalize()?;
                let line_no = capture[2].parse()?;
                let anchor_file = PathBuf::from(&capture[3]);
                let anchor_name = capture.get(4).map_or("", |m| m.as_str()).to_string();

                let the_path = include_file.parent().unwrap().join(anchor_file);

                let anchor_file = the_path.canonicalize().map_err(|err| {
                    anyhow!(
                        "{the_path:?} when canonicalized gives error {err:?}\ninclude_file: {:?}",
                        include_file
                    )
                })?;

                Ok(Include {
                    anchor_name,
                    anchor_file,
                    include_file,
                    line_no,
                })
            })
            .partition_result();
        (includes, errors)
    };

    apply_regex(
        Regex::new(r"^(\S+):(\d+):\s*\{\{\s*#include\s*(\S+?)\s*(?::\s*(\S+)\s*)?\}\}")

View on GitHub (pinned to d9a250a518)

Solutions

Read the error: it prints the exact non-canonicalizable path — verify each ../ component against the actual location of the markdown file.
Correct the anchor-file path in the include directive (it is relative to the directory of the file containing the include).
If the target file was genuinely moved/renamed, update the include to its new location.
Re-run check-docs to confirm the path resolves.

Example fix

<!-- docs/src/guide/contract.md (before): wrong depth -->
{{#include ../../examples/cookbook/src/lib.rs:my_anchor}}
<!-- after: path relative to docs/src/guide/ -->
{{#include ../../../examples/cookbook/src/lib.rs:my_anchor}}

Defensive patterns

Strategy: validation

Validate before calling

let anchor_target = include_file.parent().unwrap().join(&anchor_file_str);
if !anchor_target.exists() {
    anyhow::bail!("include anchor file does not exist: {} — fix the relative path from {}", anchor_target.display(), include_file.display());
}

Prevention

Remember anchor-file paths in includes are relative to the markdown file's directory, not the repo root.
After moving markdown files, re-run check-docs to catch broken relative paths.
Keep markdown pages at a stable directory depth or centralize includes.

When it happens

Trigger: An include line like {{#include some_file.rs:anchor}} where the third regex capture (the anchor file) resolves against the include file's parent directory to a path that does not exist — wrong relative depth (../ count), file renamed/moved, or a typo in the filename.

Common situations: Markdown files are moved between directories, breaking the relative anchor-file path; example files are renamed during refactoring; the include was written against a different checkout layout.

Related errors

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