iOfficeAI/OfficeCLI · error · ArgumentException

Picture/shape {key} is out of range for a oneCell/absolute d

Error message

Picture/shape {key} is out of range for a oneCell/absolute drawing anchor: {emu} EMU exceeds the OOXML limit 2147483647 EMU (~23.5in per axis).

What it means

Thrown by ValidateDrawingCoordEmu when a oneCell or absolute anchor coordinate/extent exceeds Int32.MaxValue (2147483647 EMU, ~23.5in). OOXML <xdr:ext> and <xdr:pos> are ST_PositiveCoordinate32 (Int32-bounded); values above pass OpenXML SDK save but fail schema validation (MaxInclusive) and make Excel refuse the workbook with 0x800A03EC. Only oneCell/absolute anchors hit this because twoCell anchors express spans via column/row markers, not raw EMU.

Source

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

        return node;
    }

    // ==================== Shared Anchor Helpers ====================

    /// <summary>
    /// Set position/size properties (x, y, width, height) on a TwoCellAnchor.
    /// Returns true if the key was handled, false otherwise.
    /// </summary>
    // OOXML spreadsheet-drawing extents/positions (<xdr:ext>, <xdr:pos>) are
    // Int32-bounded EMU (ST_PositiveCoordinate32). Values beyond that pass
    // SDK save silently but fail schema validation (MaxInclusive) and make
    // real Excel refuse the workbook (0x800A03EC) — reject at input instead
    // of persisting an unopenable file. Only oneCell/absolute anchors hit
    // this: twoCell anchors split spans into whole-column/row markers.
    internal static long ValidateDrawingCoordEmu(long emu, string key)
    {
        if (emu > int.MaxValue)
            throw new ArgumentException(
                $"Picture/shape {key} is out of range for a oneCell/absolute drawing anchor: " +
                $"{emu} EMU exceeds the OOXML limit 2147483647 EMU (~23.5in per axis).");
        return emu;
    }

    // Anchor-kind dispatch mirroring ReadAnchorPosition: oneCell keeps x/y as
    // cell indices but sizes via <xdr:ext> EMU; absolute positions and sizes
    // are all EMU (ParseEmu accepts "2cm"/"1in"/"NNNemu"/bare EMU).
    private static bool TrySetAnchorPosition(OpenXmlCompositeElement anchorEl, string key, string value)
    {
        switch (anchorEl)
        {
            case XDR.TwoCellAnchor two:
                return TrySetAnchorPosition(two, key, value);
            case XDR.OneCellAnchor one:
                switch (key)
                {
                    case "x":

View on GitHub (pinned to 1ced45e900)

Solutions

Keep each axis under ~23.5in: cap unit values (e.g. width='23in') or raw EMU to <= 2147483647.
If you genuinely need a larger span, switch to a twoCell anchor (anchor='twoCell' / cell-range) which uses column/row markers and bypasses the EMU Int32 bound.
Double-check that you are not passing a cell index where EMU is expected (or vice-versa) on a oneCell/absolute anchor.
Clamp programmatically: emu = Math.Min(emu, int.MaxValue) before calling the API.

Example fix

// before
shape anchor=oneCell x=1in width=30in
// after
shape anchor=oneCell x=1in width=20in
// or use a twoCell anchor for large spans
shape anchor=twoCell anchor=B2:F2

Defensive patterns

Strategy: validation

Validate before calling

const long OoxmlEmuMax = int.MaxValue; // 2147483647
long ClampEmuCoord(long emu) => emu > OoxmlEmuMax
    ? throw new ArgumentOutOfRangeException(nameof(emu), $"{emu} EMU exceeds OOXML Int32 limit.")
    : emu;

// before calling the anchor API on a oneCell/absolute anchor:
emu = ClampEmuCoord(emu);

Type guard

static bool IsWithinOoxmlEmuRange(long emu) => emu <= int.MaxValue;

Try / catch

try { ValidateDrawingCoordEmu(emu, key); }
catch (ArgumentException ex) when (ex.Message.Contains("exceeds the OOXML limit"))
{
    // reduce the size, or switch to a twoCell anchor that uses cell markers
}

Prevention

Keep each oneCell/absolute axis under ~23.5in (2147483647 EMU).
Use a twoCell anchor (cell range) for large spans to bypass the EMU Int32 bound.
Clamp programmatically: Math.Min(emu, int.MaxValue).
Double-check you are not feeding a cell index into an EMU-expected field.

When it happens

Trigger: Passing x/width (or y/height) on a oneCell or absolute anchor with a unit value over ~23.5 inches per axis, e.g. width='25in', x='600cm', or a raw EMU integer > 2147483647 like width='3000000000emu'. Also triggered by accidentally passing a cell count as a unit-less huge integer that the anchor path treats as EMU.

Common situations: Confusing cell-count units with EMU/inch units on oneCell anchors; AI assistants emitting 'width=30in' for a banner image; computing a size programmatically and feeding the raw pixel*9525 product without clamping; importing a drawing whose source document used a different coordinate space.

Related errors

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