What causes "Expected 1 match, but found {}" in rust-lang/rust?

Tighten the XPATH with positional predicates ([1]) or additional attribute filters until it matches a single element.

rust-lang/rust · error · FailedCheck

Expected 1 match, but found {}

Error message

Expected 1 match, but found {}

What it means

Raised by htmldocck's `snapshot` directive when the given XPATH matches more than one element. A snapshot is defined to capture exactly one subtree, so multiple matches are a FailedCheck telling you the xpath is ambiguous.

Source

Thrown at src/etc/htmldocck.py:592

                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))

        else:
            # Ignore unknown directives as they might be compiletest directives

View on GitHub (pinned to 7088e4b63a)

Solutions

Tighten the XPATH with positional predicates ([1]) or additional attribute filters until it matches a single element.
If you genuinely need to snapshot several elements, write one snapshot directive per element with a unique xpath each.

Example fix

// before
//@ snapshot item foo.html "//div[@class='item']"
// after
//@ snapshot item foo.html "(//div[@class='item'])[1]"

Defensive patterns

Strategy: validation

Validate before calling

from lxml import html as H
tree = H.parse("path/to/out.html")
n = len(tree.findall("//your/xpath"))
assert n == 1, f"snapshot xpath is ambiguous: matched {n} elements; add a [1] predicate or more attributes"

Prevention

Prefer xpaths with a unique id/class attribute to guarantee a single match.
Use positional predicates like (//foo)[1] when uniqueness cannot be guaranteed.

When it happens

Trigger: Writing `//@ snapshot name foo.html //div` against HTML where several <div> elements exist. tree.findall returns >1 subtree and the else branch at line 592 raises with the count.

Common situations: Author uses a generic tag/class xpath that the new rustdoc output now emits multiple times. The error message's count tells you how many elements matched.

Related errors

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