rust-lang/rust · error · FailedCheck

XPATH did not match

Error message

XPATH did not match

What it means

Raised by htmldocck's `snapshot` directive when the given XPATH matches zero elements in the HTML tree. This is a FailedCheck (test failure), not a directive-definition error: the directive is well-formed but the generated docs do not contain the expected structure.

Solutions

1. Open the generated HTML and locate the element you actually want, then update the XPATH.
2. Regenerate the rustdoc output and re-run the snapshot to confirm the path now resolves.
3. If the structure is genuinely gone, delete or rewrite the snapshot directive.

Example fix

// before
//@ snapshot tyname foo.html "//span[@class='tyname']"
// after (after rustdoc renamed the class)
//@ snapshot tyname foo.html "//span[@class='rustDOC-tyname']"

# Before committing a snapshot, confirm the xpath resolves in the actual output
from lxml import html as H
tree = H.parse("path/to/out.html")
assert len(tree.findall("//your/xpath")) == 1, "snapshot xpath must match exactly one element"

When it happens

Trigger: Writing `//@ snapshot name foo.html //nonexistent/path` where tree.findall returns an empty list. The `len(subtrees) == 0` branch at line 589 raises.

Common situations: rustdoc output format changed between versions and the old xpath no longer matches; the snapshot was written against a different crate structure; the html_path argument points at a file that does not contain the expected element.

Related errors

• Expected 1 match, but found
• Actual snapshot value is different than expected
• No saved snapshot value
• Non-absolute XPath is not supported due to implementation…
• Cannot parse an HTML file

AI-assisted analysis of rust-lang/rust@7088e4b63a (2026-08-10). Data as JSON: /api/errors/1a55da03a012cd65. Report an issue: GitHub.

Appendix: source

Thrown at src/etc/htmldocck.py:590

                [snapshot_name, html_path, pattern] = c.args
                tree = cache.get_tree(html_path)
                xpath = normalize_xpath(pattern)
                normalize_to_text = False
                if xpath.endswith("/text()"):
                    xpath = xpath[:-7]
                    normalize_to_text = True

                subtrees = tree.findall(xpath)
                if len(subtrees) == 1:
                    [subtree] = subtrees
                    try:
                        check_snapshot(snapshot_name, subtree, normalize_to_text)
                        ret = True
                    except FailedCheck as err:
                        cerr = str(err)
                        ret = False
                elif len(subtrees) == 0:
                    raise FailedCheck("XPATH did not match")
                else:
                    raise FailedCheck(
                        "Expected 1 match, but found {}".format(len(subtrees))
                    )
            else:
                raise InvalidCheck("Invalid number of {} arguments".format(c.cmd))

        elif c.cmd == "has-dir":  # has-dir test
            if len(c.args) == 1:  # has-dir <path> = has-dir test
                try:
                    cache.get_dir(c.args[0])
                    ret = True
                except FailedCheck as err:
                    cerr = str(err)
                    ret = False
            else:
                raise InvalidCheck("Invalid number of {} arguments".format(c.cmd))

View on GitHub (pinned to 7088e4b63a)