{"record":{"id":"076be00ec33af8b2","repo":"iOfficeAI/OfficeCLI","slug":"expected-a-non-negative-cell-index-or-a-unit-quali","errorCode":null,"errorMessage":"Expected a non-negative cell index or a unit-qualified offset (e.g. '2cm', '1in') for {name}, got '{value}'.","messagePattern":"Expected a non-negative cell index or a unit-qualified offset \\(e\\.g\\. '2cm', '1in'\\) for (.+?), got '(.+?)'\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"src/officecli/Handlers/Excel/ExcelHandler.Helpers.Drawing.cs","lineNumber":1421,"sourceCode":"    /// CONSISTENCY(ole-width-units): symmetric with width/height units.\n    /// </summary>\n    private static int ParseAnchorOrigin(string value, string name)\n    {\n        if (int.TryParse(value, out var plainInt))\n        {\n            if (plainInt < 0)\n                throw new ArgumentException($\"Picture/shape {name} must be non-negative (got '{value}').\");\n            return plainInt;\n        }\n\n        long emu;\n        try\n        {\n            emu = OfficeCli.Core.EmuConverter.ParseEmu(value);\n        }\n        catch\n        {\n            throw new ArgumentException($\"Expected a non-negative cell index or a unit-qualified offset (e.g. '2cm', '1in') for {name}, got '{value}'.\");\n        }\n        if (emu < 0)\n            throw new ArgumentException($\"Picture/shape {name} must be non-negative (got '{value}').\");\n\n        const long emuPerColApprox = 609600;\n        const long emuPerRowApprox = 190500;\n        if (name == \"y\")\n            return (int)(emu / emuPerRowApprox);\n        return (int)(emu / emuPerColApprox);\n    }\n\n    /// <summary>\n    /// Parse a width/height anchor value that is either a plain integer\n    /// cell-count (\"3\", \"5\") or a unit-qualified size (\"6cm\", \"2in\", \"72pt\").\n    /// Unit-qualified values are converted to an approximate cell count using\n    /// Excel's default ~64px (~0.66cm) column width and ~15pt row height.\n    /// CONSISTENCY(ole-width-units): Picture/Drawing elsewhere accept ParseEmu;\n    /// anchor.x/y stay as cell coordinates, but width/height tolerate EMU units.","sourceCodeStart":1403,"sourceCodeEnd":1439,"githubUrl":"https://github.com/iOfficeAI/OfficeCLI/blob/1ced45e900782c5083ed550ddf328ee974e425e7/src/officecli/Handlers/Excel/ExcelHandler.Helpers.Drawing.cs#L1403-L1439","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass a bare non-negative integer cell index: x=2.","Or pass a unit-qualified length using a supported unit (cm, mm, in, pt, pc, px, Q, emu): x='2cm'.","For cell-reference anchoring use the anchor= property (e.g. anchor='B2') instead of x/y.","Check for typos in the unit suffix and avoid unsupported units (% em ex rem vw vh)."],"exampleFix":"// before\nshape x=B2\n// after\nshape anchor=B2\n// or\nshape x=2","handlingStrategy":"validation","validationCode":"bool IsValidAnchorOrigin(string value)\n    => int.TryParse(value, out _)\n       || OfficeCli.Core.EmuConverter.TryParseEmu(value, out _);","typeGuard":"static bool IsAnchorOriginValue(string s)\n    => int.TryParse(s, out _) || OfficeCli.Core.EmuConverter.TryParseEmu(s, out _);","tryCatchPattern":"try { ParseAnchorOrigin(value, \"x\"); }\ncatch (ArgumentException ex) when (ex.Message.Contains(\"Expected a non-negative cell index\"))\n{\n    // not a cell index or unit-qualified length; surface a user error\n}","preventionTips":["Pass either a bare non-negative integer cell index or a unit-qualified length (cm/in/pt/px/emu).","Do not pass cell references (use anchor=) or percentages.","Avoid unsupported units (% em ex rem vw vh).","Pre-validate with EmuConverter.TryParseEmu when sourcing from user input."],"tags":["excel","drawing","anchor","origin","emu","units","validation"],"backgroundTag":null,"analyzedSha":"1ced45e900782c5083ed550ddf328ee974e425e7","analyzedAt":"2026-08-13T13:01:07.193Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}