larksuite/cli · error · ValueError

Range needs a maximum column: {range_ref}

Error message

Range needs a maximum column: {range_ref}

What it means

parse_range() raises this when an open-ended row range like 'Sheet1!3:5' is given but the caller did not pass max_col. A row-only range has no right edge, so the library refuses to guess a spreadsheet-wide limit and requires the caller's actual grid width to make the range finite.

Source

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

        raise ValueError(f"Invalid A1 range: {range_ref}")
    start = _parse_endpoint(parts[0])
    end = _parse_endpoint(parts[-1])

    if len(parts) == 1:
        if start[0] != "cell":
            raise ValueError(f"A1 range must include a cell or ':' separator: {range_ref}")
        _, row, col = start
        return RangeBounds(row, col, row, col)

    if start[0] == end[0] == "cell":
        _, start_row, start_col = start
        _, end_row, end_col = end
    elif start[0] == end[0] == "row":
        _, start_row = start
        _, end_row = end
        start_col = 1
        if max_col is None:
            raise ValueError(f"Range needs a maximum column: {range_ref}")
        end_col = max_col
    elif start[0] == end[0] == "column":
        _, start_col = start
        _, end_col = end
        start_row = 1
        if max_row is None:
            raise ValueError(f"Range needs a maximum row: {range_ref}")
        end_row = max_row
    elif start[0] == "cell" and end[0] == "column":
        _, start_row, start_col = start
        _, end_col = end
        if max_row is None:
            raise ValueError(f"Range needs a maximum row: {range_ref}")
        end_row = max(start_row, max_row)
    elif start[0] == "cell" and end[0] == "row":
        _, start_row, start_col = start
        _, end_row = end
        if max_col is None:

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Pass max_col explicitly: parse_range('3:5', max_col=10) or the actual column count from the fetched grid.
2. Use a fully-closed cell range instead, e.g. parse_range('A3:J5'), which needs no max_col.
3. If dimensions are unknown, fetch the grid first (sheet metadata / returned rows) and then call parse_range with those dimensions.

Example fix

// before
bounds = parse_range("3:5")
// after
bounds = parse_range("3:5", max_col=len(header_row))  # or max_col=26

from lark_sheet_range import parse_range, _parse_endpoint

def is_open_row_range(ref: str) -> bool:
    """True if ref is row:row form and will require max_col."""
    body = ref.strip().rsplit("!", 1)[-1]
    parts = body.split(":")
    return len(parts) == 2 and all(_looks_row(p) for p in parts)

def _looks_row(p: str) -> bool:
    p = p.lstrip("$")
    return p.isdigit() and int(p) >= 1

# call site
if is_open_row_range(ref):
    assert max_col is not None, f"{ref} needs max_col"
bounds = parse_range(ref, max_col=max_col)

def needs_max_col(ref: str) -> bool:
    body = ref.strip().rsplit("!", 1)[-1]
    parts = body.split(":")
    if len(parts) != 2:
        return False
    import re
    row_re = re.compile(r"^\$?([1-9][0-9]*)$")
    return bool(row_re.match(parts[0].strip()) and row_re.match(parts[-1].strip()))

try:
    bounds = parse_range(ref, max_col=max_col)
except ValueError as e:
    if "maximum column" in str(e):
        bounds = parse_range(ref, max_col=grid_col_count)  # retry with fetched width
    else:
        raise

When it happens

Trigger: Calling parse_range('3:5') (or 'A3:5' style row endpoints) without the max_col keyword, or calling one of its wrappers (parse_annotated_csv, _external_merge_anchors, build_occupancy, profile_grid) with a row-range but no known grid width.

Common situations: Handing a rows-only A1 range from a config file or user input to a CSV-export helper that only knows dimensions after fetching data; scripting '+csv-get' with a range like '1:10' when the script forgot to pass the fetched sheet's column count.

Related errors

• Range needs a maximum row: {range_ref}
• +csv-get truncated the requested range at {source_range}; na
• Invalid column: {col}
• Column index must be >= 1: {index}
• Row must be >= 1: {row}

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