iOfficeAI/OfficeCLI · error · ArgumentException

Expected a non-negative cell index or a unit-qualified offse

Error message

Expected a non-negative cell index or a unit-qualified offset (e.g. '2cm', '1in') for {name}, got '{value}'.

What it means

Thrown by ParseAnchorOrigin when the value is not a plain integer AND cannot be parsed as a unit-qualified length by EmuConverter.ParseEmu. ParseAnchorOrigin accepts either a non-negative cell index ('0','5') or a unit-qualified offset ('2cm','1in','72pt') that it converts to an approximate cell index. Anything else is syntactically invalid.

Source

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

    /// 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")
            return (int)(emu / emuPerRowApprox);
        return (int)(emu / emuPerColApprox);
    }

    /// <summary>
    /// Parse a width/height anchor value that is either a plain integer
    /// cell-count ("3", "5") or a unit-qualified size ("6cm", "2in", "72pt").
    /// Unit-qualified values are converted to an approximate cell count using
    /// Excel's default ~64px (~0.66cm) column width and ~15pt row height.
    /// CONSISTENCY(ole-width-units): Picture/Drawing elsewhere accept ParseEmu;
    /// anchor.x/y stay as cell coordinates, but width/height tolerate EMU units.

View on GitHub (pinned to 1ced45e900)

Solutions

  1. Pass a bare non-negative integer cell index: x=2.
  2. Or pass a unit-qualified length using a supported unit (cm, mm, in, pt, pc, px, Q, emu): x='2cm'.
  3. For cell-reference anchoring use the anchor= property (e.g. anchor='B2') instead of x/y.
  4. Check for typos in the unit suffix and avoid unsupported units (% em ex rem vw vh).

Example fix

// before
shape x=B2
// after
shape anchor=B2
// or
shape x=2
Defensive patterns

Strategy: validation

Validate before calling

bool IsValidAnchorOrigin(string value)
    => int.TryParse(value, out _)
       || OfficeCli.Core.EmuConverter.TryParseEmu(value, out _);

Type guard

static bool IsAnchorOriginValue(string s)
    => int.TryParse(s, out _) || OfficeCli.Core.EmuConverter.TryParseEmu(s, out _);

Try / catch

try { ParseAnchorOrigin(value, "x"); }
catch (ArgumentException ex) when (ex.Message.Contains("Expected a non-negative cell index"))
{
    // not a cell index or unit-qualified length; surface a user error
}

Prevention

When it happens

Trigger: Passing x='abc', x='1foo', x='B2' (a cell reference is not valid here - use the anchor= path), x='50%' (percent not supported), or x='5em' (font-relative unit unsupported by EmuConverter). The inner EmuConverter.ParseEmu exception is wrapped and re-thrown with this clearer message.

Common situations: Confusing the x/y origin property with the anchor= cell-reference property; passing CSS units like % or em that EmuConverter does not support; typos in unit suffixes; expecting percentage-based positioning.

Related errors

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