larksuite/cli · error

unsupported range form %q (need rectangular A1:B2)

Error message

unsupported range form %q (need rectangular A1:B2)

What it means

When a range contains a colon, parseCellRange validates both halves with splitCellRef; if either the start or end half is not a valid cell reference, it reports 'unsupported range form' with the full body. This is the range-form counterpart of the single-cell invalid-ref error and is wrapped by callers into a typed --range/--source-range validation error.

Source

Thrown at shortcuts/sheets/lark_sheet_write_cells.go:1156

	}
	if body == "" {
		return out, fmt.Errorf("empty range") //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
	}
	parts := strings.SplitN(body, ":", 2)
	out.start = strings.TrimSpace(parts[0])
	startCol, startRow, ok := splitCellRef(out.start)
	out.col, out.row = startCol, startRow
	if len(parts) == 1 {
		// single cell, e.g. "A1"
		if !ok {
			return cellRange{}, fmt.Errorf("invalid cell ref %q", parts[0]) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
		}
		out.rows, out.cols, out.anchored = 1, 1, true
		return out, nil
	}
	endCol, endRow, okEnd := splitCellRef(parts[1])
	if !ok || !okEnd {
		return cellRange{}, fmt.Errorf("unsupported range form %q (need rectangular A1:B2)", body) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
	}
	if endRow < startRow || endCol < startCol {
		return cellRange{}, fmt.Errorf("end %q must be at or after start %q", parts[1], parts[0]) //nolint:forbidigo // intermediate error; callers wrap it into a typed --range/--source-range validation error
	}
	out.rows, out.cols = endRow-startRow+1, endCol-startCol+1
	return out, nil
}

func rangeDimensions(rangeStr string) (rows, cols int, err error) {
	r, err := parseCellRange(rangeStr)
	if err != nil {
		return 0, 0, err
	}
	return r.rows, r.cols, nil
}

// splitCellRef parses "A1" → (col=0, row=0, true). Returns false for any
// non-rectangular form (pure column "A", pure row "1", invalid chars).

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Reformat as exactly two valid cell refs joined by one colon, e.g. 'A1:B2'.
2. Replace whole-column ('A:C') or whole-row ('1:1') specs with explicit bounding cells like 'A1:C100'.
3. Remove extra spaces around the colon; splitCellRef requires tight cell refs.
4. Verify with --help/schema examples of the accepted --range syntax.

Example fix

// before
--range "A:C"
--range "A1:B2:C3"
// after
--range "A1:C100"
--range "A1:B2"

parts := strings.Split(strings.TrimSpace(rng), ":")
if len(parts) != 2 || !cellRe.MatchString(parts[0]) || !cellRe.MatchString(parts[1]) {
	return fmt.Errorf("--range %q: use exactly A1:B2", rng)
}

func isRectRange(s string) bool {
	parts := strings.SplitN(s, ":", 2)
	return len(parts) == 2 && isCellRef(parts[0]) && isCellRef(strings.TrimSpace(parts[1]))
}

When it happens

Trigger: Passing two-part ranges where either side is malformed, e.g. 'A1:B2:C3' (extra part beyond the first colon is glued into the end half), 'A1:2B', ':B2', 'A1:', or column-only ranges like 'A:C'.

Common situations: Using Excel-style whole-column/whole-row ranges, named ranges, multi-area ranges ('A1:B2 C3:D4'), or accidental extra colons/whitespace.

Related errors

• unsupported range form %q (need rectangular A1:B2)
• end %q must be at or after start %q
• empty range
• invalid cell ref %q
• end %q must be at or after start %q

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