larksuite/cli · error

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

Error message

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

What it means

The sheet workbook range parser only accepts a rectangular A1:B2 style range: two cell references separated by a colon, each a column-letter + row-number cell ref. It throws this error when the given range string does not split into exactly two parseable cell references. It is an intermediate error; the calling command wraps it into a typed validation error with flag/param context.

Source

Thrown at shortcuts/sheets/lark_sheet_workbook.go:2121

	if idx := strings.Index(rangeStr, "!"); idx >= 0 {
		rangeStr = rangeStr[idx+1:]
	}
	rangeStr = strings.TrimSpace(rangeStr)
	if rangeStr == "" {
		return 0, 0, 0, 0, fmt.Errorf("empty range") //nolint:forbidigo // intermediate error; callers wrap it into a typed validation error with flag/param context
	}
	parts := strings.SplitN(rangeStr, ":", 2)
	if len(parts) == 1 {
		col, row, ok := splitCellRef(parts[0])
		if !ok {
			return 0, 0, 0, 0, fmt.Errorf("invalid cell ref %q", parts[0]) //nolint:forbidigo // intermediate error; callers wrap it into a typed validation error with flag/param context
		}
		return col, row, col, row, nil
	}
	startCol, startRow, ok1 := splitCellRef(parts[0])
	endCol, endRow, ok2 := splitCellRef(parts[1])
	if !ok1 || !ok2 {
		return 0, 0, 0, 0, fmt.Errorf("unsupported range form %q (need rectangular A1:B2)", rangeStr) //nolint:forbidigo // intermediate error; callers wrap it into a typed validation error with flag/param context
	}
	if endRow < startRow || endCol < startCol {
		return 0, 0, 0, 0, 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 validation error with flag/param context
	}
	return startCol, startRow, endCol, endRow, nil
}

// mergeWorkbookCreateStyle merges one cell_styles op's style map into a cell.
// cell_styles / border_styles are nested submaps: they are deep-merged one level
// (field-wise, last write wins) so overlapping cell_styles ops accumulate fields
// rather than the later op's submap wholesale-replacing the earlier one. A fresh
// submap is allocated each merge so the op.Style shared across the range's cells
// is never mutated.
func mergeWorkbookCreateStyle(cell interface{}, style map[string]interface{}) {
	if len(style) == 0 {
		return
	}
	m, ok := cell.(map[string]interface{})

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Reformat the value as a rectangular range 'startCell:endCell', e.g. 'A1:B2'; for a single cell use the single-cell form accepted by the command.
2. Remove any sheet-name prefix or extra separators (spaces, extra colons) from the range string.
3. Run the command with --help or `schema` to see the documented --range format and examples.
4. If wrapping this parser yourself, surface the returned error with the flag/param context as the callers do.

Example fix

// before
--range "A1"
--range "Sheet1!A1:B2"
// after
--range "A1:B2"

var rangeRe = regexp.MustCompile(`^[A-Za-z]+[1-9][0-9]*:[A-Za-z]+[1-9][0-9]*$`)
func validRectRange(s string) bool { return rangeRe.MatchString(strings.TrimSpace(s)) }
if !validRectRange(rangeStr) { return fmt.Errorf("bad --range %q; use A1:B2", rangeStr) }

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

When it happens

Trigger: Calling a sheet workbook shortcut with a --range (or equivalent) flag set to a string that is not '<cell>:<cell>', e.g. 'A1', 'A1:', ':B2', 'A1:B2:C3', 'Sheet1!A1:B2' if the qualifier was not stripped, or references like '1A:2B' that splitCellRef cannot parse.

Common situations: Users copying range syntax from Excel UI ('A1' single cell in the two-part parser), passing whole-column ranges ('A:C'), named ranges, or including extra whitespace/formatting the parser does not accept.

Related errors

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

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