iOfficeAI/OfficeCLI · error · ArgumentException

Invalid 'width' value: '{value}'. Column width must be betwe

Error message

Invalid 'width' value: '{value}'. Column width must be between 0 and 255 character units.

What it means

Thrown by ParseColWidthChars after a successful parse when the resulting width in character units falls outside Excel's [0, 255] bound. Excel rejects files with out-of-range column widths, so this validates at Set time.

Source

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

        }
        else
        {
            try
            {
                var emu = OfficeCli.Core.EmuConverter.ParseEmu(trimmed);
                // 9525 EMU = 1 px; 7 px ≈ 1 char unit (Calibri 11pt MDW baseline)
                var px = emu / EmuConverter.EmuPerPxF;
                chars = px / 7.0;
            }
            catch (Exception ex)
            {
                throw new ArgumentException($"Invalid 'width' value: '{value}'. Expected a finite number or unit-qualified value (e.g. 8.43, 20px, 2cm, 1in, 60pt).", ex);
            }
        }
        // DEFERRED(xlsx/row-height-validation) RC2: Excel column width is bounded
        // [0, 255] character units. Validate at Set time.
        if (chars < 0 || chars > 255)
            throw new ArgumentException($"Invalid 'width' value: '{value}'. Column width must be between 0 and 255 character units.");
        return chars;
    }

    // Returns true if `s` would parse as a valid cell reference (e.g. A1,
    // TBL1, XFD1048576). Excel refuses to open files whose table names match
    // this pattern — the name is ambiguous with a cell address.
    internal static bool LooksLikeCellReference(string? s)
    {
        if (string.IsNullOrEmpty(s)) return false;
        var m = System.Text.RegularExpressions.Regex.Match(s, @"^\$?([A-Za-z]{1,3})\$?([0-9]+)$");
        if (!m.Success) return false;
        var col = m.Groups[1].Value.ToUpperInvariant();
        var colIdx = 0;
        foreach (var ch in col) colIdx = colIdx * 26 + (ch - 'A' + 1);
        if (colIdx < 1 || colIdx > 16384) return false;
        if (!long.TryParse(m.Groups[2].Value, out var row) || row < 1 || row > 1048576) return false;
        return true;
    }

View on GitHub (pinned to 1ced45e900)

Solutions

Clamp the value into [0, 255] character units (Excel's documented maximum column width is 255).
If you intended pixels, note the 7-px-per-char approximation: char_units ≈ pixels / 7.
Re-check the unit; 255 char units is roughly 1785px, 47cm, or 18.7in.

Example fix

// before
set /Sheet1/col[B] --prop width=300

// after
set /Sheet1/col[B] --prop width=255

Defensive patterns

Strategy: validation

Validate before calling

const double ColWidthMax = 255.0;
double chars = ExcelHandler.ParseColWidthChars(value);   // assume parse succeeded
if (chars < 0 || chars > ColWidthMax)
    throw new ArgumentException($"Column width {chars} char-units is out of [0, {ColWidthMax}].");

Prevention

Clamp column widths to [0, 255] character units before setting.
Approximate char-units from pixels as pixels/7.

When it happens

Trigger: Passing width=300, width=-3, or a unit conversion whose char-unit value exceeds 255 (e.g. width=50cm ≈ 283 char units -> rejected).

Common situations: Treating the value as pixels (width=255 thinking 255px ≈ 36 char units, which is fine, but width=2000px ≈ 285 char units is rejected); negative widths from a sign error; very large physical conversions.

Related errors

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