{"record":{"id":"6ff0f641ca4673f1","repo":"larksuite/cli","slug":"header-scan-rows-must-be-at-least-1","errorCode":null,"errorMessage":"--header-scan-rows must be at least 1","messagePattern":"--header-scan-rows must be at least 1","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"skills/lark-sheets/scripts/lark_profile_table.py","lineNumber":532,"sourceCode":"    the grid precisely because they are hidden.\n    \"\"\"\n    letters: list[str] = []\n    raw = layout.get(\"hidden_cols\") or layout.get(\"hidden_columns\") or []\n    for value in raw if isinstance(raw, list) else []:\n        if isinstance(value, str) and value.isalpha():\n            letters.append(value.upper())\n            continue\n        try:\n            letters.append(index_to_col(int(value) + 1))\n        except (TypeError, ValueError):\n            continue\n    return letters\n\n\ndef profile_table(args) -> tuple[dict[str, Any], list[str]]:\n    warnings = []\n    if args.header_scan_rows < 1:\n        raise ValueError(\"--header-scan-rows must be at least 1\")\n    csv_data = envelope_data(\n        run_sheets(\n            \"+csv-get\",\n            url=args.url,\n            spreadsheet_token=args.spreadsheet_token,\n            sheet_id=args.sheet_id,\n            sheet_name=args.sheet_name,\n            flags={\n                \"range\": args.range,\n                \"max_chars\": args.max_chars,\n                \"skip_hidden\": True if args.skip_hidden else None,\n            },\n            timeout=args.timeout,\n        )\n    )\n    source_range = str(csv_data.get(\"actual_range\") or args.range)\n    if csv_data.get(\"has_more\"):\n        raise LarkCliError(","sourceCodeStart":514,"sourceCodeEnd":550,"githubUrl":"https://github.com/larksuite/cli/blob/7fd6ef3c07182257ce776cdc5a614e122d5bd4b3/skills/lark-sheets/scripts/lark_profile_table.py#L514-L550","documentation":"profile_table validates that --header-scan-rows is at least 1 before doing any work, raising a plain ValueError with this message. The header scan needs at least one row to detect column headers, so 0 or negative values are meaningless. This is an upfront argument guard, not an API failure.","triggerScenarios":"Calling profile_table (or the lark_profile_table.py script) with args.header_scan_rows set to 0 or a negative number, e.g. --header-scan-rows 0 on the command line.","commonSituations":"Users try to disable header detection by passing 0; a wrapper script computes the value (e.g. len(rows)-1) and yields 0 for a one-row sheet; copy-pasted config with an empty or negative setting.","solutions":["Pass --header-scan-rows with a value of 1 or higher (e.g. --header-scan-rows 1).","If you intended to skip header detection, use whatever option disables header handling instead of 0 rows.","Fix the calling script so it clamps the computed value: max(1, computed_rows)."],"exampleFix":"# before\nsubprocess.run([... \"--header-scan-rows\", \"0\" ...])\n# after\nsubprocess.run([... \"--header-scan-rows\", \"1\" ...])","handlingStrategy":"validation","validationCode":"rows = int(args.header_scan_rows)\nif rows < 1:\n    raise ValueError(f\"--header-scan-rows must be >= 1, got {rows}\")","typeGuard":"def valid_header_scan_rows(v: object) -> bool:\n    return isinstance(v, int) and not isinstance(v, bool) and v >= 1","tryCatchPattern":"try:\n    data, warnings = profile_table(args)\nexcept ValueError as e:\n    if \"header-scan-rows\" in str(e):\n        args.header_scan_rows = 1\n        data, warnings = profile_table(args)\n    else:\n        raise","preventionTips":["Default --header-scan-rows to 1 and only raise it for multi-row headers.","Never pass 0 expecting to disable header detection; look for a dedicated skip-header option.","Clamp computed values with max(1, value) before invoking the CLI."],"tags":["cli","argument-validation","python"],"backgroundTag":"invalid-argument-value","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"}