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

No anchor available to satisfy include {include:?}

Error message

No anchor available to satisfy include {include:?}

What it means

Doc-checking script error (scripts/check-docs): a markdown {{#include path:anchor_name}} reference could not be matched to any valid ANCHOR/ANCHOR_END pair. The include directives in markdown files are paired with named anchors embedded in source files; if the target anchor does not exist (wrong name or wrong file), this error is reported with the offending Include's details.

Source

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

        }
    }
}

pub fn validate_includes(
    includes: Vec<Include>,
    valid_anchors: Vec<Anchor>,
) -> (Vec<Error>, Vec<Error>) {
    let (pairs, errors): (Vec<_>, Vec<_>) = includes
        .into_iter()
        .filter(|include| !include.anchor_name.is_empty())
        .map(|include| {
            let mut maybe_anchor = valid_anchors.iter().find(|anchor| {
                anchor.file == include.anchor_file && anchor.name == include.anchor_name
            });

            match maybe_anchor.take() {
                Some(anchor) => Ok(anchor.clone()),
                None => Err(anyhow!(
                    "No anchor available to satisfy include {include:?}"
                )),
            }
        })
        .partition_result();

    let additional_warnings = valid_anchors
        .iter()
        .filter(|valid_anchor| {
            let anchor_used_in_a_pair = pairs.iter().any(|anchor| anchor == *valid_anchor);
            !anchor_used_in_a_pair
        })
        .map(|unused_anchor| anyhow!("Anchor unused: {unused_anchor:?}!"))
        .collect::<Vec<_>>();

    (errors, additional_warnings)
}

View on GitHub (pinned to d9a250a518)

Solutions

1. Open the include location reported in the error (include_file + line_no) and read the anchor_name it references.
2. In the target source file, add ANCHOR: <name> before the snippet and ANCHOR_END: <name> after it, using exactly the referenced name.
3. If the anchor was renamed, update the markdown include to the new name (or the source back to the old one).
4. Run cargo run -p check-docs (or the docs CI job) to confirm the pairing now succeeds.

Example fix

// docs/src/contract.md (before)
{{#include ../../../examples/cookbook/src/lib.rs:missing_anchor}}
// examples/cookbook/src/lib.rs (after): add matching markers
// ANCHOR: missing_anchor
pub async fn my_example() { /* ... */ }
// ANCHOR_END: missing_anchor

use std::fs;
let (text, _) = (fs::read_to_string(&md)?, ());
for cap in INCLUDE_RE.captures_iter(&text) {
    let anchor_file = path_from(cap[3]);
    let src = fs::read_to_string(&anchor_file)?;
    let name = cap.get(4).map(|m| m.as_str()).unwrap_or("");
    assert!(
        src.lines().any(|l| l.contains(&format!("ANCHOR: {name}"))),
        "anchor '{name}' missing in {anchor_file:?}"
    );
}

When it happens

Trigger: A docs markdown file contains an include line whose anchor_name (4th regex capture) has no matching ANCHOR: <name> ... ANCHOR_END: <name> block in the canonicalized anchor_file — e.g. an anchor was renamed/deleted in the example code, or the include points at the wrong file.

Common situations: Refactoring example snippets removes/renames ANCHOR markers while the docs still reference the old name; moving source files so the relative anchor path in the include no longer resolves to the file holding the anchor; copy-pasting an include line and forgetting to update the anchor name.

Related errors

• Couldn't find a matching end anchor for {start:?}
• Anchor unused: {unused_anchor:?}!
• The end of the anchor appears before the beginning. End anch
• {the_path:?} when canonicalized gives error {err:?}\ninclude
• file `{}` not in SUMMARY.md

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