What causes "Expected list as second argument of {} (ie '[]')" in rust-lang/rust?

Wrap the file list in square brackets: `//@ files: mydir [file1.html file2.html]`.

rust-lang/rust · error · InvalidCheck

Expected list as second argument of {} (ie '[]')

Error message

Expected list as second argument of {} (ie '[]')

What it means

Raised as InvalidCheck by check_files_in_folder() when the second argument (the file list) of a 'files' directive does not start with '[' and end with ']'. The files directive expects a bracketed list literal (e.g. `//@ files: dir [a.html b.html]`) so it can be parsed with shlex after stripping the brackets.

Source

Thrown at src/etc/htmldocck.py:477

def get_nb_matching_elements(cache, c, regexp, stop_at_first):
    tree = cache.get_tree(c.args[0])
    pat, sep, attr = c.args[1].partition("/@")
    if sep:  # attribute
        tree = cache.get_tree(c.args[0])
        return check_tree_attr(tree, pat, attr, c.args[2], False)
    else:  # normalized text
        pat = c.args[1]
        if pat.endswith("/text()"):
            pat = pat[:-7]
        return check_tree_text(
            cache.get_tree(c.args[0]), pat, c.args[2], regexp, stop_at_first
        )


def check_files_in_folder(c, cache, folder, files):
    files = files.strip()
    if not files.startswith("[") or not files.endswith("]"):
        raise InvalidCheck(
            "Expected list as second argument of {} (ie '[]')".format(c.cmd)
        )

    folder = cache.get_absolute_path(folder)

    # First we create a set of files to check if there are duplicates.
    files = shlex.split(files[1:-1].replace(",", ""))
    files_set = set()
    for file in files:
        if file in files_set:
            raise InvalidCheck("Duplicated file `{}` in {}".format(file, c.cmd))
        files_set.add(file)
    folder_set = set([f for f in os.listdir(folder) if f != "." and f != ".."])

    # Then we remove entries from both sets (we clone `folder_set` so we can iterate it while
    # removing its elements).
    for entry in set(folder_set):
        if entry in files_set:

View on GitHub (pinned to 7088e4b63a)

Solutions

Wrap the file list in square brackets: `//@ files: mydir [file1.html file2.html]`.
Ensure nothing trails after the closing ']' on that directive line.
Separate entries with spaces (commas are tolerated because they are replaced before shlex).

Example fix

// before
//@ files: mydir file1.html file2.html

// after
//@ files: mydir [file1.html file2.html]

Defensive patterns

Strategy: validation

Validate before calling

def files_list_well_formed(files_str: str) -> bool:
    return files_str.strip().startswith("[") and files_str.strip().endswith("]")

if not files_list_well_formed(files_arg):
    raise SystemExit(f"files directive list must be wrapped in [...]; got {files_arg!r}")

Type guard

def is_valid_files_list(s: str) -> bool:
    s = s.strip()
    return s.startswith("[") and s.endswith("]")

Try / catch

from srcetc_htmldocck import InvalidCheck
try:
    check_files_in_folder(c, cache, folder, files)
except InvalidCheck as e:
    if "Expected list as second argument" in str(e):
        logging.error("wrap the files list in square brackets: [a.html b.html]")
    raise

Prevention

Always wrap the files directive's list argument in square brackets.
Lint files directives in a pre-commit hook to enforce the bracket shape.
Keep a documented example of each directive form in the test-authoring guide.

When it happens

Trigger: Authoring a `//@ files: <folder> <list>` directive where <list> is not wrapped in square brackets. Reached at htmldocck.py:476-479 after the files-strip at line 475.

Common situations: Forgetting the brackets; using parentheses or braces instead; pasting a comma-separated list without brackets; trailing characters after the closing bracket break the endswith(']') check.

Related errors

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