larksuite/cli · error

invalid cell ref %q

Error message

invalid cell ref %q

What it means

workbookCreateStyleRangeBounds splits a range on ':' and parses each side as a cell reference like 'A1'. This error is returned when a single-cell range (no colon) is not a valid cell ref — the token isn't a column-letters + row-number combination. It is an intermediate error wrapped by callers into a typed validation error with flag/param context.

Source

Thrown at shortcuts/sheets/lark_sheet_workbook.go:2114

		return input, "modify_sheet_structure"
	default:
		return nil, ""
	}
}

func workbookCreateStyleRangeBounds(rangeStr string) (startCol, startRow, endCol, endRow int, err error) {
	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

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Use a valid A1 cell reference, e.g. 'B2' for a single cell or 'B2:D4' for a block.
2. Replace whole-column/whole-row ranges ('A:A', '1:1') with explicit bounded ranges ('A1:A100').
3. Check the typed validation error's context to see exactly which token failed to parse.
4. Validate with a regex like ^[A-Za-z]+[1-9][0-9]*$ before submitting.

Example fix

// before
{"styles": [{"range": "A:A", "bold": true}]}
// after
{"styles": [{"range": "A1:A100", "bold": true}]}

var cellRefRe = regexp.MustCompile(`^[A-Za-z]{1,3}[1-9][0-9]*$`)
func validRange(r string) bool {
	if i := strings.Index(r, "!"); i >= 0 { r = r[i+1:] }
	parts := strings.SplitN(r, ":", 2)
	for _, p := range parts { if !cellRefRe.MatchString(strings.TrimSpace(p)) { return false } }
	return len(parts) >= 1
}

When it happens

Trigger: lark sheet table put with a styles/merge range of 'A', '3', 'AA', '1A', or other strings without a colon that splitCellRef cannot parse into a (col,row) pair.

Common situations: Typos like 'A1:' variants, whole-column 'A:A' or whole-row '1:1' style ranges, or using named ranges instead of A1 notation.

Related errors

• empty range
• Range needs a maximum column: {range_ref}
• Range needs a maximum row: {range_ref}
• %s got conflicting values for %q under two spellings (%q and
• %s got both %q and %q — keep %q and drop the other

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