iOfficeAI/OfficeCLI · error · ArgumentException

Anchor cell '{original}' is outside Excel's grid (A1..XFD104

Error message

Anchor cell '{original}' is outside Excel's grid (A1..XFD1048576).

What it means

Thrown by ValidateAnchorCell when a parsed 0-based anchor cell falls outside Excel's real grid (A1..XFD1048576, i.e. col 0..16383, row 0..1048575). The check exists because Row 0 ('A0') parses to row index -1 and columns past XFD wrap into indices Excel refuses (0x800A03EC) while OOXML schema validation stays green - the parser rejects at parse time instead of persisting an unopenable file.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Helpers.Drawing.cs:1597

    /// <summary>Swap anchor corners per axis so from ≤ to.</summary>
    internal static void NormalizeAnchorRect(ref int fromCol, ref int fromRow, ref int toCol, ref int toRow)
    {
        if (toCol >= 0 && toCol < fromCol) (fromCol, toCol) = (toCol, fromCol);
        if (toRow >= 0 && toRow < fromRow) (fromRow, toRow) = (toRow, fromRow);
    }

    /// <summary>
    /// Bounds-check a parsed 0-based anchor cell against Excel's real grid
    /// (A1..XFD1048576). Row 0 (A0) parses to -1 and columns past XFD wrap
    /// into indices Excel refuses (0x800A03EC) while schema validation stays
    /// green — reject at parse time instead.
    /// </summary>
    internal static void ValidateAnchorCell(int col0, int row0, string original)
    {
        const int MaxCol0 = 16383;      // XFD
        const int MaxRow0 = 1048575;    // 1,048,576 rows, 0-based
        if (col0 < 0 || col0 > MaxCol0 || row0 < 0 || row0 > MaxRow0)
            throw new ArgumentException(
                $"Anchor cell '{original}' is outside Excel's grid (A1..XFD1048576).");
    }

    /// <summary>
    /// Clamp a TwoCellAnchor span computed from x/y/width/height (column/row
    /// units) to Excel's grid. The FROM marker must be a real cell
    /// (A1..XFD1048576) and still throws if outside it. The TO marker is the
    /// exclusive right/bottom edge, so it may legitimately sit one past the last
    /// cell (col 16384 / row 1048576) — a picture/shape placed near XFD simply
    /// ends at the grid edge, which is what real Excel does. A width/height that
    /// walks the TO marker further than that (e.g. x=1,width=16384 → toCol 16385)
    /// was silently persisted and made Excel refuse the file (0x800A03EC), so the
    /// TO marker is clamped to the ceiling here rather than written out of range.
    /// Returns the clamped (toCol, toRow).
    /// </summary>
    internal static (int toCol, int toRow) ClampAnchorSpan(int fromCol, int fromRow, int toCol, int toRow, string original)
    {
        ValidateAnchorCell(fromCol, fromRow, original);

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Use a valid cell in A1..XFD1048576: anchor='B2'.
  2. Remember Excel references are 1-based: the first row is '1', not '0'.
  3. Clamp computed column index to [0, 16383] and row index to [0, 1048575] before formatting the reference.
  4. Validate with a cell-reference parser and reject 'A0' / past-XFD columns upstream.

Example fix

// before
shape anchor=A0
// after
shape anchor=A1
Defensive patterns

Strategy: validation

Validate before calling

// Excel grid: A1..XFD1048576 -> 0-based col [0,16383], row [0,1048575]
const int MaxCol0 = 16383, MaxRow0 = 1048575;
bool IsValidAnchorCell(int col0, int row0)
    => col0 >= 0 && col0 <= MaxCol0 && row0 >= 0 && row0 <= MaxRow0;

// reject 'A0' (row 0 -> -1) and past-XFD columns before formatting the reference.

Type guard

static bool IsWithinExcelGrid(int col0, int row0)
    => col0 >= 0 && col0 <= 16383 && row0 >= 0 && row0 <= 1048575;

Try / catch

try { ValidateAnchorCell(col0, row0, original); }
catch (ArgumentException ex) when (ex.Message.Contains("outside Excel's grid"))
{
    // clamp col0/row0 into range, or surface a user error
}

Prevention

When it happens

Trigger: Passing anchor='A0' (row 0 -> index -1), anchor='XFE1' (column past XFD), anchor='A1048577' (row past the 1048576 limit), or any cell reference whose parsed column/row is out of range. Triggered via the anchor= cell-reference/range path.

Common situations: Off-by-one errors in computed cell references; assuming 0-based rows in the reference string ('A0'); passing a column letter sequence past XFD; programmatic row/column overflow.

Related errors

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