{"record":{"id":"e33badec5269ac11","repo":"larksuite/cli","slug":"no-matching-sheet-found","errorCode":null,"errorMessage":"No matching sheet found","messagePattern":"No matching sheet found","errorType":"exception","errorClass":"LarkCliError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_sheet_read_cli.py","lineNumber":182,"sourceCode":"    workbook_data: dict[str, Any],\n    *,\n    sheet_id: str | None = None,\n    sheet_name: str | None = None,\n    require_one: bool = False,\n) -> list[dict[str, Any]]:\n    sheets = extract_sheets(workbook_data)\n    if sheet_id:\n        matches = [sheet for sheet in sheets if sheet_identifier(sheet) == sheet_id]\n    elif sheet_name:\n        matches = [sheet for sheet in sheets if sheet_title(sheet) == sheet_name]\n    else:\n        matches = sheets\n\n    if require_one:\n        if len(matches) == 1:\n            return matches\n        if not matches:\n            raise LarkCliError(\"No matching sheet found\")\n        raise LarkCliError(\"Multiple sheets matched; pass --sheet-id or --sheet-name\")\n    return matches\n","sourceCodeStart":164,"sourceCodeEnd":185,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_sheet_read_cli.py#L164-L185","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"# before: brittle exact-name match fails after a rename\nmatches = resolve_target_sheets(data, sheet_name=\"Q3 Budget\", require_one=True)\n# after: resolve case/whitespace-insensitively or list candidates first\ntitles = [sheet_title(s) for s in extract_sheets(data)]\nif \"Q3 Budget\" not in titles:\n    raise LarkCliError(f\"Sheet 'Q3 Budget' not found; available: {titles}\")\nmatches = resolve_target_sheets(data, sheet_name=\"Q3 Budget\", require_one=True)","handlingStrategy":"validation","validationCode":"from lark_sheet_read_cli import extract_sheets, sheet_title, sheet_identifier\n\ndef assert_sheet_exists(workbook_data: dict, sheet_id: str | None = None, sheet_name: str | None = None) -> None:\n    sheets = extract_sheets(workbook_data)\n    if sheet_id and not any(sheet_identifier(s) == sheet_id for s in sheets):\n        raise ValueError(f\"sheet-id {sheet_id!r} not in {[sheet_identifier(s) for s in sheets]}\")\n    if sheet_name and not any(sheet_title(s) == sheet_name for s in sheets):\n        raise ValueError(f\"sheet-name {sheet_name!r} not in {[sheet_title(s) for s in sheets]}\")","typeGuard":null,"tryCatchPattern":"from lark_sheet_read_cli import LarkCliError\ntry:\n    sheets = resolve_target_sheets(data, sheet_name=name, require_one=True)\nexcept LarkCliError as exc:\n    if str(exc) == \"No matching sheet found\":\n        available = [sheet_title(s) for s in extract_sheets(data)]\n        print(f\"{name!r} not found; available sheets: {available}\")\n    raise","preventionTips":["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."],"tags":["sheet-resolution","user-input","name-mismatch","lark-sheets"],"backgroundTag":"sheet-not-found","analyzedSha":"7fd6ef3c07182257ce776cdc5a614e122d5bd4b3","analyzedAt":"2026-09-04T21:17:44.649Z","contentChangedAt":"2026-09-04T21:17:44.649Z","schemaVersion":2},"datasetVersion":"2026-09-12T02:17:10.037Z"}