iOfficeAI/OfficeCLI · error · ArgumentException

Invalid cell reference: '{cellRef}'. Expected format like 'A

Error message

Invalid cell reference: '{cellRef}'. Expected format like 'A1', 'B2'.

What it means

Thrown by the Excel Get path when the trailing path segment is pure digits (matches ^\d+$), e.g. '/Sheet1/123'. A digit-only segment is neither a valid A1 cell reference nor a recognized element keyword (picture/shape/sparkline), so rather than letting it fall through to generic-XML navigation and return a misleading 'Element not found', the handler rejects it early with the expected A1 format.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Query.cs:895

                    ?? throw new ArgumentException(
                        $"Picture[{picIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).");
            }

            // Handle shape[N] path segment
            var shpMatch = Regex.Match(cellRef, @"^shape\[(\d+)\]$", RegexOptions.IgnoreCase);
            if (shpMatch.Success)
            {
                var shpIndex = int.Parse(shpMatch.Groups[1].Value);
                // Same null-leak as picture[N] above.
                return GetShapeNode(sheetNameFromPath, worksheet, shpIndex, path)
                    ?? throw new ArgumentException(
                        $"Shape[{shpIndex}] not found in sheet '{sheetNameFromPath}' (indices are 1-based).");
            }


            // If it looks like it could be a malformed cell reference (digits only, etc.), reject it
            if (Regex.IsMatch(cellRef, @"^\d+$"))
                throw new ArgumentException($"Invalid cell reference: '{cellRef}'. Expected format like 'A1', 'B2'.");

            // CONSISTENCY(axis-ref-compat): Excel-style whole-column/row
            // references (B:B, 1:1) are input aliases for col[X]/row[N] —
            // re-dispatch a single-axis span to the canonical path (readback
            // Path stays canonical). Multi-axis spans (B:D) have no single
            // node to return; point at the bracket syntax instead.
            if (TryExpandAxisRef(cellRef) is { } axisSegments)
            {
                if (axisSegments.Count == 1)
                    return Get($"/{sheetNameFromPath}/{axisSegments[0]}", depth);
                throw new ArgumentException(
                    $"{cellRef} spans multiple {(char.IsDigit(cellRef[0]) ? "rows" : "columns")} — get them one at a time ({axisSegments[0]} … {axisSegments[^1]}); set accepts the whole span.");
            }

            // Generic XML fallback: navigate worksheet XML tree
            var xmlSegments = GenericXmlQuery.ParsePathSegments(cellRef);
            var target = GenericXmlQuery.NavigateByPath(GetSheet(worksheet), xmlSegments);
            if (target == null)

View on GitHub (pinned to 1ced45e900)

Solutions

Prefix the row number with its column letter to form a real A1 reference, e.g. /Sheet1/A123 instead of /Sheet1/123.
If you meant a positional row, use the bracket form /Sheet1/row[123] (1-based), which is the canonical positional selector.
If you meant a whole row span, use /Sheet1/row[123] or the axis alias 123:123, not a bare 123.

Example fix

// before
get /Sheet1/123
// after
get /Sheet1/A123   // a specific cell
get /Sheet1/row[123] // positional row

Defensive patterns

Strategy: validation

Validate before calling

import re
def valid_cell_ref(seg):
    # A1-style: one or more letters then digits, within sheet limits
    m = re.fullmatch(r'([A-Za-z]+)(\d+)', seg)
    if not m: return False
    col, row = m.group(1).upper(), int(m.group(2))
    from functools import reduce
    idx = reduce(lambda a, c: a * 26 + (ord(c) - 64), col, 0)
    return 1 <= idx <= 16384 and 1 <= row <= 1048576

# before building a get path
seg = '123'
assert valid_cell_ref(seg), f"'{seg}' is not an A1 cell reference; use /Sheet1/row[N] for a positional row"

Type guard

null

Try / catch

null

Prevention

Always build cell paths as column-letter + row-number (A1), never a bare index.
Use the row[N] bracket form when you mean a positional row.
Validate generated path segments with an A1 regex before sending.

When it happens

Trigger: Calling get with a path whose cell-ref segment is all digits: get /Sheet1/42, or a range typo like /Sheet1/123:130 written without column letters. Also reached when a programmatic path builder emits an index where a cell coordinate belongs.

Common situations: Indexing loops that build paths as f"/Sheet/{i}" instead of f"/Sheet/A{i}"; copy-pasting row numbers from a spreadsheet into a path; confusing the positional row[N] bracket syntax (which is valid) with a bare digit segment.

Related errors

AI-assisted analysis of iOfficeAI/OfficeCLI@1ced45e900 (2026-08-13). Data as JSON: /api/errors/262a5e0ce0a4833b. Report an issue: GitHub.