larksuite/cli · error · ValueError

Column index must be >= 1: {index}

Error message

Column index must be >= 1: {index}

What it means

index_to_col converts a 1-based column number back to letters (1->A, 26->Z, 27->AA) and rejects any index below 1, since spreadsheet columns are 1-based and there is no valid representation for 0 or negatives. Raising here prevents silently emitting an empty string or looping forever on invalid input.

Source

Thrown at skills/lark-sheets/scripts/lark_sheet_range.py:44

    @property
    def col_count(self) -> int:
        return self.end_col - self.start_col + 1


def col_to_index(col: str) -> int:
    value = 0
    for char in col.strip().upper():
        if not ("A" <= char <= "Z"):
            raise ValueError(f"Invalid column: {col}")
        value = value * 26 + (ord(char) - ord("A") + 1)
    if value <= 0:
        raise ValueError(f"Invalid column: {col}")
    return value


def index_to_col(index: int) -> str:
    if index < 1:
        raise ValueError(f"Column index must be >= 1: {index}")
    chars = []
    n = index
    while n:
        n, rem = divmod(n - 1, 26)
        chars.append(chr(ord("A") + rem))
    return "".join(reversed(chars))


def parse_cell(cell_ref: str) -> tuple[int, int]:
    match = CELL_RE.match(cell_ref.strip())
    if not match:
        raise ValueError(f"Invalid cell reference: {cell_ref}")
    col, row = match.groups()
    return int(row), col_to_index(col)


def _parse_endpoint(endpoint: str) -> tuple[str, int, int] | tuple[str, int]:
    cell = CELL_RE.match(endpoint)

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Pass 1-based indices; add +1 when converting from zero-based collections: index_to_col(zero_based + 1).
2. Guard before calling: if index >= 1: index_to_col(index) else handle the invalid case.
3. Fix the upstream code producing the index so it uses the correct 1-based base.

Example fix

# before
letters = index_to_col(csv_col_index)  # 0-based -> ValueError
# after
letters = index_to_col(csv_col_index + 1)

def to_col_letters(zero_based: int) -> str:
    if zero_based < 0:
        raise ValueError(f"zero-based index must be >= 0, got {zero_based}")
    return index_to_col(zero_based + 1)

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

try:
    letters = index_to_col(index)
except ValueError as e:
    if "must be >= 1" in str(e):
        letters = "A"  # or handle the out-of-bounds column explicitly
    else:
        raise

When it happens

Trigger: Calling index_to_col(0), index_to_col(-3), or any index computed from off-by-one arithmetic, e.g. zero-based col_indices passed where 1-based letters are expected.

Common situations: Mixing zero-based array indices from parsed CSV output with this 1-based helper; a computed column minus 1 (idx-1) reaching 0 on the first column; uninitialized/default integer values of 0.

Related errors

• Invalid column: {col}
• Row must be >= 1: {row}
• +csv-get truncated the requested range at {source_range}; na
• Invalid cell reference: {cell_ref}
• Invalid A1 range endpoint: {endpoint}

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