{"record":{"id":"67775deab4567f20","repo":"larksuite/cli","slug":"multiple-sheets-matched-pass-sheet-id-or-shee","errorCode":null,"errorMessage":"Multiple sheets matched; pass --sheet-id or --sheet-name","messagePattern":"Multiple sheets matched; pass --sheet-id or --sheet-name","errorType":"exception","errorClass":"LarkCliError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_sheet_read_cli.py","lineNumber":183,"sourceCode":"    *,\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":165,"sourceCodeEnd":185,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_sheet_read_cli.py#L165-L185","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Pass --sheet-id with the unique sheet identifier (the long token from the sheet URL or the sheets list) to target exactly one sheet.","Pass --sheet-name with a title that matches exactly one sheet; rename duplicate tabs in the spreadsheet if titles collide.","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).","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."],"exampleFix":"// before\nlark sheets read --spreadsheet-id <id>\n// after\nlark sheets read --spreadsheet-id <id> --sheet-name \"Q3 Revenue\"\n# or unambiguously:\nlark sheets read --spreadsheet-id <id> --sheet-id <sheet-token>","handlingStrategy":"validation","validationCode":"matches = resolve_target_sheets(workbook_data, sheet_id=args.sheet_id, sheet_name=args.sheet_name)\nif len(matches) != 1:\n    print(\"available sheets:\", [(s.get(\"sheet_id\"), s.get(\"title\")) for s in matches])\n    raise SystemExit(\"pass --sheet-id or a unique --sheet-name\")","typeGuard":null,"tryCatchPattern":"try:\n    sheets = resolve_target_sheets(workbook, sheet_id=opt.sheet_id, sheet_name=opt.sheet_name, require_one=True)\nexcept LarkCliError as err:\n    if \"Multiple sheets matched\" in str(err):\n        print(\"disambiguate with --sheet-id; candidates:\", [s.get(\"title\") for s in extract_sheets(workbook)])\n    raise","preventionTips":["Always script against --sheet-id for automation; reserve --sheet-name for interactive use on workbooks you control.","Enforce unique sheet titles in templates and generation code.","List sheets (ids + titles) before running a one-sheet command on an unfamiliar workbook."],"tags":["cli","ambiguity","sheets","input-validation"],"backgroundTag":"ambiguous-sheet-selector","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"}