What causes "glob path does not resolve to one file" in rust-lang/rust?

Tighten the glob pattern so it matches exactly one file (add more path components or a more specific stem).

rust-lang/rust · error · FailedCheck

glob path does not resolve to one file

Error message

glob path does not resolve to one file

What it means

Raised as FailedCheck by CachedFiles.get_absolute_path() when a path containing '*' is globbed (Path(self.root).glob(path)) and the result does not contain exactly one file. htmldocck allows '*' in directive paths as a convenience but requires the glob to be unambiguous so a single concrete file is selected.

Source

Thrown at src/etc/htmldocck.py:249

        self.files = {}
        self.trees = {}
        self.last_path = None

    def resolve_path(self, path):
        if path != "-":
            path = os.path.normpath(path)
            self.last_path = path
            return path
        elif self.last_path is None:
            raise InvalidCheck("Tried to use the previous path in the first command")
        else:
            return self.last_path

    def get_absolute_path(self, path):
        if "*" in path:
            paths = list(Path(self.root).glob(path))
            if len(paths) != 1:
                raise FailedCheck("glob path does not resolve to one file")
            return str(paths[0])
        return os.path.join(self.root, path)

    def get_file(self, path):
        path = self.resolve_path(path)
        if path in self.files:
            return self.files[path]

        abspath = self.get_absolute_path(path)
        if not (os.path.exists(abspath) and os.path.isfile(abspath)):
            raise FailedCheck("File does not exist {!r}".format(path))

        with io.open(abspath, encoding="utf-8") as f:
            data = f.read()
            self.files[path] = data
            return data

    def get_tree(self, path):

View on GitHub (pinned to 7088e4b63a)

Solutions

Tighten the glob pattern so it matches exactly one file (add more path components or a more specific stem).
Verify the expected file actually exists under the doc output root and matches the glob.
Replace the glob with a concrete filename if the name is known and stable.

Example fix

// before
//@ has: crate/*.html 'index'   // matches 0 or many

// after
//@ has: crate/crate.index.html 'index'   // concrete single file

Defensive patterns

Strategy: validation

Validate before calling

from pathlib import Path

def glob_resolves_to_one(root, pattern) -> bool:
    return len(list(Path(root).glob(pattern))) == 1

if '*' in path and not glob_resolves_to_one(doc_root, path):
    raise SystemExit(f"glob {path!r} did not resolve to exactly one file under {doc_root}")

Type guard

null

Try / catch

from srcetc_htmldocck import FailedCheck
try:
    abspath = cache.get_absolute_path(path)
except FailedCheck as e:
    if "glob path does not resolve" in str(e):
        logging.error("tighten the glob or use a concrete filename")
    raise

Prevention

Prefer concrete filenames over globs in directives.
If a glob is necessary, make it specific enough to match exactly one file.
Re-validate directive globs whenever the rustdoc output layout changes.

When it happens

Trigger: A directive references a path with '*' (e.g. `//@ has: foo/*.html '...'`) and, at check time, zero files match (typo, output not generated) or more than one file matches (ambiguous glob). Reached at htmldocck.py:248-249.

Common situations: The rustdoc output filename changed so the old glob matches nothing; the glob is too broad and matches multiple generated files (e.g. multiple crates); the test runs before output is fully written.

Related errors

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