What causes "Picture/shape {name} must be non-negative (got '{value}')." in iOfficeAI/OfficeCLI?

Use a non-negative cell index for x and y: x=0, y=2.

iOfficeAI/OfficeCLI · error · ArgumentException

Picture/shape {name} must be non-negative (got '{value}').

Error message

Picture/shape {name} must be non-negative (got '{value}').

What it means

Thrown by ParseAnchorOrigin when a plain-integer x/y anchor origin parses successfully but is negative. Anchor origins (x, y) are 0-based cell indices for the FROM marker of a twoCell anchor; a negative index would write an invalid <xdr:col>/<xdr:row> that Excel rejects. The guard rejects the bare-integer form before any unit conversion is attempted.

Source

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

            ParseAnchorOrigin(properties.GetValueOrDefault("y", defY) ?? defY, "y"),
            ParseAnchorDimension(widthRaw, "width"),
            ParseAnchorDimension(heightRaw, "height")
        );
    }

    /// <summary>
    /// Parse an anchor origin value (x/y) that is either a plain non-negative
    /// integer cell index ("0", "5") or a unit-qualified offset ("2cm", "1in",
    /// "72pt"). Unit-qualified values are converted to a cell index using the
    /// same approximate EMU/column and EMU/row factors as ParseAnchorDimension.
    /// CONSISTENCY(ole-width-units): symmetric with width/height units.
    /// </summary>
    private static int ParseAnchorOrigin(string value, string name)
    {
        if (int.TryParse(value, out var plainInt))
        {
            if (plainInt < 0)
                throw new ArgumentException($"Picture/shape {name} must be non-negative (got '{value}').");
            return plainInt;
        }

        long emu;
        try
        {
            emu = OfficeCli.Core.EmuConverter.ParseEmu(value);
        }
        catch
        {
            throw new ArgumentException($"Expected a non-negative cell index or a unit-qualified offset (e.g. '2cm', '1in') for {name}, got '{value}'.");
        }
        if (emu < 0)
            throw new ArgumentException($"Picture/shape {name} must be non-negative (got '{value}').");

        const long emuPerColApprox = 609600;
        const long emuPerRowApprox = 190500;
        if (name == "y")

View on GitHub (pinned to 1ced45e900)

Solutions

Use a non-negative cell index for x and y: x=0, y=2.
If you need a sub-cell offset within the FROM cell, use a oneCell/absolute anchor with EMU units instead of a negative twoCell origin.
Clamp the computed value to >= 0 before passing.
Switch to a cell-reference anchor= like 'B2' which is always non-negative by construction.

Example fix

// before
shape anchor=twoCell x=-2 y=0
// after
shape anchor=twoCell x=0 y=0

Defensive patterns

Strategy: validation

Validate before calling

bool IsValidOriginInt(string value)
    => int.TryParse(value, out var i) && i >= 0;

Type guard

static bool IsNonNegativeCellIndex(string s)
    => int.TryParse(s, out var i) && i >= 0;

Try / catch

try { ParseAnchorOrigin(value, "x"); }
catch (ArgumentException ex) when (ex.Message.Contains("must be non-negative"))
{
    // clamp to 0 or surface a user error
}

Prevention

Use a non-negative integer cell index for x/y origins.
Clamp computed origins to >= 0.
Use a cell-reference anchor= for guaranteed-non-negative positioning.
Validate the sign before passing if sourcing from computed offsets.

When it happens

Trigger: Passing x=-5 or y=-1 as a bare integer on an anchor that routes through ParseAnchorOrigin. The unit-qualified negative case (e.g. '-1in') is a separate code path that throws at line 1424 with the same message text.

Common situations: Negative offsets copied from a coordinate system with a different origin (e.g. screen-space top-left with negative y for 'up'); AI assistants defaulting unknown x/y to -1; programmatic subtraction underflowing past zero.

Related errors

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