larksuite/cli · error

expected pure digits (row number) or letters (column letter)

Error message

expected pure digits (row number) or letters (column letter), got %q

What it means

parseA1Position parses a single A1-notation token (like "3" for row 3 or "B" for column B) into a dimension type plus 0-based index. This error is thrown when the token is neither pure digits nor pure letters, e.g. "B3", "", or "1A" — those belong to full A1 ranges, not single-position input. Callers wrap it into a typed flag validation error.

Source

Thrown at shortcuts/sheets/lark_sheet_sheet_structure.go:872

	for _, r := range s {
		if r < '0' || r > '9' {
			isDigits = false
		}
		if !((r >= 'A' && r <= 'Z') || (r >= 'a' && r <= 'z')) {
			isLetters = false
		}
	}
	if isDigits {
		n, _ := strconv.Atoi(s)
		if n <= 0 {
			return "", 0, fmt.Errorf("row number must be >= 1 (got %q)", s) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
		}
		return "row", n - 1, nil
	}
	if isLetters {
		return "column", letterToColumnIndex(s), nil
	}
	return "", 0, fmt.Errorf("expected pure digits (row number) or letters (column letter), got %q", s) //nolint:forbidigo // intermediate error; callers wrap it into a typed flag validation error
}

// columnIndexToLetter converts a 0-based column index to the spreadsheet
// letter notation (0 → "A", 25 → "Z", 26 → "AA", 701 → "ZZ", 702 → "AAA").
// Used by +workbook helpers that need to format absolute column references.
func columnIndexToLetter(idx int) string {
	if idx < 0 {
		return ""
	}
	idx++
	var out []byte
	for idx > 0 {
		idx--
		out = append([]byte{byte('A' + idx%26)}, out...)
		idx /= 26
	}
	return string(out)
}

View on GitHub (pinned to 7fd6ef3c07)

Solutions

1. Strip the cell reference to the single part needed: for rows pass only digits ("3"), for columns only letters ("B")
2. If you mean a range, use the range-accepting flag/notation (A1:B3) instead of a position flag
3. Trim whitespace and re-check the token for stray characters before invoking the command

Example fix

// before
lark sheet dim-insert --position B3 ...
// after
lark sheet dim-insert --position 3 ...   # row index
lark sheet dim-insert --position B ...   # column letter

function isValidA1Position(s) { return /^[0-9]+$/.test(s) || /^[A-Za-z]+$/.test(s); }
if (!isValidA1Position(pos)) throw new Error(`--position must be digits (row) or letters (column), got ${pos}`);

function isA1Position(v) { return typeof v === 'string' && (/^[0-9]+$/.test(v) || /^[A-Za-z]+$/.test(v)); }

try {
  await run(['lark','sheet','dim-insert','--position',pos]);
} catch (e) {
  if (/expected pure digits/.test(e.message)) {
    throw new Error(`Fix --position '${pos}': use digits for rows or letters for columns`);
  }
  throw e;
}

When it happens

Trigger: Passing a cell reference like "B3" or "A1" to a dimension flag that expects only a row number or only a column letter; passing an empty or whitespace/mixed token (e.g. "1A", "3.5", "C;") to sheet dim insert/move/before flags.

Common situations: Users habitually paste full cell references (B3) where the flag wants just the row number (3) or column letter (B); typos with stray characters; shell quoting introducing extra chars.

Understand the failure class

Background: "unknown output mode", "invalid value for flag", "expects true/false": fixing invalid flag value errors in CLI tools — this error's family across 24 libraries.

Related errors

• number expects a numeric value, got %s
• bool expects true/false, got %s
• date expects an ISO yyyy-mm-dd string, got %s
• unsupported type %q
• date column has an empty cell — drop the empty rows, fill re

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