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.

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)

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 {}
• Non-absolute XPath is not supported due to implementation is
• No saved snapshot value
• Actual snapshot value is different than expected
• line {}: {}

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