larksuite/cli · error · ValueError

--header-scan-rows must be at least 1

Error message

--header-scan-rows must be at least 1

What it means

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.

Source

Thrown at skills/lark-sheets/scripts/lark_profile_table.py:532

    the grid precisely because they are hidden.
    """
    letters: list[str] = []
    raw = layout.get("hidden_cols") or layout.get("hidden_columns") or []
    for value in raw if isinstance(raw, list) else []:
        if isinstance(value, str) and value.isalpha():
            letters.append(value.upper())
            continue
        try:
            letters.append(index_to_col(int(value) + 1))
        except (TypeError, ValueError):
            continue
    return letters


def profile_table(args) -> tuple[dict[str, Any], list[str]]:
    warnings = []
    if args.header_scan_rows < 1:
        raise ValueError("--header-scan-rows must be at least 1")
    csv_data = envelope_data(
        run_sheets(
            "+csv-get",
            url=args.url,
            spreadsheet_token=args.spreadsheet_token,
            sheet_id=args.sheet_id,
            sheet_name=args.sheet_name,
            flags={
                "range": args.range,
                "max_chars": args.max_chars,
                "skip_hidden": True if args.skip_hidden else None,
            },
            timeout=args.timeout,
        )
    )
    source_range = str(csv_data.get("actual_range") or args.range)
    if csv_data.get("has_more"):
        raise LarkCliError(

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Pass --header-scan-rows with a value of 1 or higher (e.g. --header-scan-rows 1).
2. If you intended to skip header detection, use whatever option disables header handling instead of 0 rows.
3. Fix the calling script so it clamps the computed value: max(1, computed_rows).

Example fix

# before
subprocess.run([... "--header-scan-rows", "0" ...])
# after
subprocess.run([... "--header-scan-rows", "1" ...])

rows = int(args.header_scan_rows)
if rows < 1:
    raise ValueError(f"--header-scan-rows must be >= 1, got {rows}")

def valid_header_scan_rows(v: object) -> bool:
    return isinstance(v, int) and not isinstance(v, bool) and v >= 1

try:
    data, warnings = profile_table(args)
except ValueError as e:
    if "header-scan-rows" in str(e):
        args.header_scan_rows = 1
        data, warnings = profile_table(args)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Pass exactly one of --url or --spreadsheet-token
• Pass only one of --sheet-id or --sheet-name
• +csv-get truncated the requested range at {source_range}; na
• lark-cli exited with {completed.returncode}
• {message}

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