larksuite/cli · error · LarkCliError

Multiple sheets matched; pass --sheet-id or --sheet-name

Error message

Multiple sheets matched; pass --sheet-id or --sheet-name

What it means

resolve_target_sheets picks which sheets of a workbook to operate on. When require_one is set, the command needs exactly one target sheet; if the filter (no --sheet-id/--sheet-name given, or an ambiguous value) matches more than one sheet, it raises LarkCliError telling you to disambiguate rather than guessing which sheet you meant. This is an input-ambiguity guard, not an API failure — no Lark request result is involved.

Source

Thrown at skills/lark-sheets/scripts/lark_sheet_read_cli.py:183

    *,
    sheet_id: str | None = None,
    sheet_name: str | None = None,
    require_one: bool = False,
) -> list[dict[str, Any]]:
    sheets = extract_sheets(workbook_data)
    if sheet_id:
        matches = [sheet for sheet in sheets if sheet_identifier(sheet) == sheet_id]
    elif sheet_name:
        matches = [sheet for sheet in sheets if sheet_title(sheet) == sheet_name]
    else:
        matches = sheets

    if require_one:
        if len(matches) == 1:
            return matches
        if not matches:
            raise LarkCliError("No matching sheet found")
        raise LarkCliError("Multiple sheets matched; pass --sheet-id or --sheet-name")
    return matches

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Pass --sheet-id with the unique sheet identifier (the long token from the sheet URL or the sheets list) to target exactly one sheet.
2. Pass --sheet-name with a title that matches exactly one sheet; rename duplicate tabs in the spreadsheet if titles collide.
3. If you actually want all matching sheets, use a command path that does not set require_one (resolve_target_sheets without require_one returns every match).
4. List the workbook's sheets first (e.g. the read/inspect entry point that returns all sheets) to see the available ids and titles before re-running.

Example fix

// before
lark sheets read --spreadsheet-id <id>
// after
lark sheets read --spreadsheet-id <id> --sheet-name "Q3 Revenue"
# or unambiguously:
lark sheets read --spreadsheet-id <id> --sheet-id <sheet-token>

matches = resolve_target_sheets(workbook_data, sheet_id=args.sheet_id, sheet_name=args.sheet_name)
if len(matches) != 1:
    print("available sheets:", [(s.get("sheet_id"), s.get("title")) for s in matches])
    raise SystemExit("pass --sheet-id or a unique --sheet-name")

try:
    sheets = resolve_target_sheets(workbook, sheet_id=opt.sheet_id, sheet_name=opt.sheet_name, require_one=True)
except LarkCliError as err:
    if "Multiple sheets matched" in str(err):
        print("disambiguate with --sheet-id; candidates:", [s.get("title") for s in extract_sheets(workbook)])
    raise

When it happens

Trigger: Running a sheets subcommand that requires one sheet while (1) omitting both --sheet-id and --sheet-name on a multi-sheet workbook, (2) passing a --sheet-name that matches two or more sheets with the same title, or (3) passing a name/id that broad-matches multiple sheets via resolve_target_sheets(workbook, require_one=True).

Common situations: Workbooks created from a template where every sheet is titled 'Sheet1'; a workbook with duplicated sheet names across locales; scripting a read against a default spreadsheet without specifying which tab; forgetting that omitting the selector implies 'all sheets' and the command demands exactly one.

Related errors

• +csv-get truncated the requested range at {source_range}; na
• column labels collide after str() conversion; rename the Dat
• name must not be empty
• name %q must not include leading dashes
• name %q must not contain whitespace

AI-assisted analysis of larksuite/cli@7fd6ef3c07 (2026-09-04). Data as JSON: /api/errors/67775deab4567f20. Report an issue: GitHub.