{"record":{"id":"590ca320c890d5c6","repo":"FuelLabs/fuels-rs","slug":"the-path-when-canonicalized-gives-error-err","errorCode":null,"errorMessage":"{the_path:?} when canonicalized gives error {err:?}\\ninclude_file: {:?}","messagePattern":"(.+?) when canonicalized gives error (.+?)\\\\ninclude_file: (.+?)","errorType":"exception","errorClass":"anyhow::Error","httpStatus":null,"severity":"error","filePath":"scripts/check-docs/src/lib.rs","lineNumber":84,"sourceCode":"    pub include_file: PathBuf,\n    pub line_no: usize,\n}\n\npub fn parse_includes(text_w_includes: String) -> (Vec<Include>, Vec<Error>) {\n    let apply_regex = |regex: Regex| {\n        let (includes, errors): (Vec<_>, Vec<_>) = text_w_includes\n            .lines()\n            .filter_map(|line| regex.captures(line))\n            .map(|capture| {\n                let include_file = PathBuf::from(&capture[1]).canonicalize()?;\n                let line_no = capture[2].parse()?;\n                let anchor_file = PathBuf::from(&capture[3]);\n                let anchor_name = capture.get(4).map_or(\"\", |m| m.as_str()).to_string();\n\n                let the_path = include_file.parent().unwrap().join(anchor_file);\n\n                let anchor_file = the_path.canonicalize().map_err(|err| {\n                    anyhow!(\n                        \"{the_path:?} when canonicalized gives error {err:?}\\ninclude_file: {:?}\",\n                        include_file\n                    )\n                })?;\n\n                Ok(Include {\n                    anchor_name,\n                    anchor_file,\n                    include_file,\n                    line_no,\n                })\n            })\n            .partition_result();\n        (includes, errors)\n    };\n\n    apply_regex(\n        Regex::new(r\"^(\\S+):(\\d+):\\s*\\{\\{\\s*#include\\s*(\\S+?)\\s*(?::\\s*(\\S+)\\s*)?\\}\\}\")","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/FuelLabs/fuels-rs/blob/d9a250a51818dda64bfeb5ef7cc19cf27bdcd623/scripts/check-docs/src/lib.rs#L66-L102","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"<!-- docs/src/guide/contract.md (before): wrong depth -->\n{{#include ../../examples/cookbook/src/lib.rs:my_anchor}}\n<!-- after: path relative to docs/src/guide/ -->\n{{#include ../../../examples/cookbook/src/lib.rs:my_anchor}}","handlingStrategy":"validation","validationCode":"let anchor_target = include_file.parent().unwrap().join(&anchor_file_str);\nif !anchor_target.exists() {\n    anyhow::bail!(\"include anchor file does not exist: {} — fix the relative path from {}\", anchor_target.display(), include_file.display());\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["docs","check-docs","paths","file-not-found"],"backgroundTag":null,"analyzedSha":"d9a250a51818dda64bfeb5ef7cc19cf27bdcd623","analyzedAt":"2026-08-16T09:49:30.618Z","schemaVersion":2},"datasetVersion":"2026-08-16T13:17:31.715Z"}