{"record":{"id":"de231a410d37c143","repo":"larksuite/cli","slug":"pass-only-one-of-sheet-id-or-sheet-name","errorCode":null,"errorMessage":"Pass only one of --sheet-id or --sheet-name","messagePattern":"Pass only one of --sheet-id or --sheet-name","errorType":"validation","errorClass":"LarkCliError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_sheet_read_cli.py","lineNumber":57,"sourceCode":"        cmd.append(flag if value else f\"{flag}=false\")\n        return\n    cmd.extend([flag, str(value)])\n\n\ndef run_sheets(\n    shortcut: str,\n    *,\n    url: str | None = None,\n    spreadsheet_token: str | None = None,\n    sheet_id: str | None = None,\n    sheet_name: str | None = None,\n    flags: dict[str, Any] | None = None,\n    timeout: int = 60,\n) -> dict[str, Any]:\n    if bool(url) == bool(spreadsheet_token):\n        raise LarkCliError(\"Pass exactly one of --url or --spreadsheet-token\")\n    if sheet_id and sheet_name:\n        raise LarkCliError(\"Pass only one of --sheet-id or --sheet-name\")\n\n    cmd = [\"lark-cli\", \"sheets\", shortcut]\n    _append_flag(cmd, \"url\", url)\n    _append_flag(cmd, \"spreadsheet_token\", spreadsheet_token)\n    _append_flag(cmd, \"sheet_id\", sheet_id)\n    _append_flag(cmd, \"sheet_name\", sheet_name)\n    for key, value in (flags or {}).items():\n        _append_flag(cmd, key, value)\n\n    try:\n        completed = subprocess.run(\n            cmd,\n            capture_output=True,\n            text=True,\n            timeout=timeout,\n            check=False,\n        )\n    except FileNotFoundError as exc:","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_sheet_read_cli.py#L39-L75","documentation":"run_sheets() also requires the target sheet within the spreadsheet to be identified in exactly one way: --sheet-id or --sheet-name. When both are truthy it raises LarkCliError, since the two selectors could disagree and the CLI accepts only one.","triggerScenarios":"Calling run_sheets() with both sheet_id and sheet_name set, e.g. code that resolves a sheet by name but then also forwards the resolved id.","commonSituations":"Scripts that look up the sheet id by name and then pass both 'just in case'; users copying flags from --help output; config layers where one source supplies the id and another supplies the name.","solutions":["Pass only sheet_id if you have it (ids are stable); drop sheet_name.","Pass only sheet_name if that is what the user provided; let the CLI resolve it.","If your code resolves the id from the name, keep only the id and remove the original name from the call."],"exampleFix":"// before\nsheet_id = lookup_id_by_name(name)\nrun_sheets(\"read\", url=url, sheet_id=sheet_id, sheet_name=name)  # LarkCliError\n\n// after\nrun_sheets(\"read\", url=url, sheet_id=lookup_id_by_name(name))","handlingStrategy":"validation","validationCode":"if sheet_id and sheet_name:\n    raise SystemExit(\"Provide only one of --sheet-id or --sheet-name\")","typeGuard":"def has_one_sheet_selector(sheet_id, sheet_name) -> bool:\n    return bool(sheet_id) != bool(sheet_name)","tryCatchPattern":"try:\n    data = run_sheets(shortcut, url=url, sheet_id=sheet_id, sheet_name=sheet_name)\nexcept LarkCliError as e:\n    if \"only one of --sheet-id\" in str(e):\n        data = run_sheets(shortcut, url=url, sheet_id=sheet_id)  # prefer stable id\n    else:\n        raise","preventionTips":["Resolve sheet names to ids once at startup and forward only the id.","In CLI wrappers, make --sheet-id and --sheet-name mutually exclusive flags.","Keep one canonical sheet selector in shared config rather than both."],"tags":["python","cli","argument-validation","mutually-exclusive"],"backgroundTag":"conflicting-arguments","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"}