What causes "No matching sheet found" in larksuite/cli?

Run the same command without --sheet-id/--sheet-name to list all sheets in the workbook, then copy the exact id/title from the output.

larksuite/cli · error · LarkCliError

No matching sheet found

Error message

No matching sheet found

What it means

resolve_target_sheets() filters the workbook's sheet list by --sheet-id (exact sheet_identifier match) or --sheet-name (exact sheet_title match) and, when require_one is set, insists on exactly one match. This error is raised when the filter matched zero sheets — the requested sheet does not exist in the fetched workbook data under the given id or exact title. It is a user-input/targeting error, not a transport failure.

Source

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

    workbook_data: dict[str, Any],
    *,
    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

Run the same command without --sheet-id/--sheet-name to list all sheets in the workbook, then copy the exact id/title from the output.
If matching by name, verify exact title spelling, case, and whitespace (matching is strict equality via sheet_title).
Confirm the --url/--spreadsheet-token points at the spreadsheet that actually contains the target sheet.
Fetch fresh workbook metadata (`sheets info`) in case the sheet list is stale and the sheet was deleted or renamed.
Use --sheet-id instead of --sheet-name for stable automation, since ids survive renames.

Example fix

# before: brittle exact-name match fails after a rename
matches = resolve_target_sheets(data, sheet_name="Q3 Budget", require_one=True)
# after: resolve case/whitespace-insensitively or list candidates first
titles = [sheet_title(s) for s in extract_sheets(data)]
if "Q3 Budget" not in titles:
    raise LarkCliError(f"Sheet 'Q3 Budget' not found; available: {titles}")
matches = resolve_target_sheets(data, sheet_name="Q3 Budget", require_one=True)

Defensive patterns

Strategy: validation

Validate before calling

from lark_sheet_read_cli import extract_sheets, sheet_title, sheet_identifier

def assert_sheet_exists(workbook_data: dict, sheet_id: str | None = None, sheet_name: str | None = None) -> None:
    sheets = extract_sheets(workbook_data)
    if sheet_id and not any(sheet_identifier(s) == sheet_id for s in sheets):
        raise ValueError(f"sheet-id {sheet_id!r} not in {[sheet_identifier(s) for s in sheets]}")
    if sheet_name and not any(sheet_title(s) == sheet_name for s in sheets):
        raise ValueError(f"sheet-name {sheet_name!r} not in {[sheet_title(s) for s in sheets]}")

Try / catch

from lark_sheet_read_cli import LarkCliError
try:
    sheets = resolve_target_sheets(data, sheet_name=name, require_one=True)
except LarkCliError as exc:
    if str(exc) == "No matching sheet found":
        available = [sheet_title(s) for s in extract_sheets(data)]
        print(f"{name!r} not found; available sheets: {available}")
    raise

Prevention

List all sheets first (omit --sheet-id/--sheet-name) and copy ids/titles verbatim from the output.
Prefer --sheet-id over --sheet-name in automations; ids are stable across renames.
Re-fetch workbook metadata whenever the spreadsheet may have been edited.
Normalize case/whitespace in names before passing them, since matching is exact equality.

When it happens

Trigger: Calling main, detect_subtables, or inspect_workbook with --sheet-id/--sheet-name that matches no sheet: a typo'd sheet id, a sheet renamed so the exact title no longer matches, passing --sheet-name for a deleted/hidden sheet not present in the sheets list, or a sheet-id belonging to a different spreadsheet than the one addressed by --url/--spreadsheet-token.

Common situations: Sheet was renamed after the script/automation was written; copying a sheet-id from a different spreadsheet; trailing whitespace or case differences in the title (matching is exact equality); the sheet is a embedded/foreign sheet not returned by the workbook metadata; using the spreadsheet's display name instead of the sheet (tab) name.

Related errors

expected RFC3339, YYYY-MM-DD[ HH:MM:SS], or unix seconds

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