iOfficeAI/OfficeCLI · error · ArgumentException

number format is {formatCode.Length} chars; Excel's limit is

Error message

number format is {formatCode.Length} chars; Excel's limit is 255.

What it means

Thrown by the Excel number-format writer when a custom format code exceeds 255 characters. Excel itself enforces this cap (ECMA-376 stores it in a bounded field), so the write path fails fast instead of relying on a separate schema-validate run. A format over 255 chars makes Excel refuse to open the produced file.

Source

Thrown at src/officecli/Core/ExcelStyleManager.cs:721

        for (int i = 0; i < formatCode.Length; i++)
        {
            var c = formatCode[i];
            if (c == '"') nfInQuote = !nfInQuote;
            else if (!nfInQuote && c == '[') nfInBracket = true;
            else if (!nfInQuote && c == ']') nfInBracket = false;
            else if (!nfInQuote && c == '\\') i++;
            else if (!nfInQuote && !nfInBracket && c == ';') nfSections++;
        }
        if (nfSections > 4)
            throw new ArgumentException(
                $"number format has {nfSections} sections: '{formatCode}'. Excel allows " +
                "at most 4 (positive;negative;zero;text); more makes Excel refuse to open the file.");

        // Excel caps format codes at 255 chars; schema validate flags it but
        // the write path should fail fast rather than rely on a separate
        // validate run.
        if (formatCode.Length > 255)
            throw new ArgumentException(
                $"number format is {formatCode.Length} chars; Excel's limit is 255.");

        // Unbalanced [brackets] (e.g. formatCode="[") pass schema validation
        // but real Excel refuses the whole file (0x800A03EC). Count outside
        // quoted literals; escaped \[ is a literal char.
        int nfBracketDepth = 0;
        bool nfBrQuote = false;
        for (int i = 0; i < formatCode.Length; i++)
        {
            var c = formatCode[i];
            if (c == '"') nfBrQuote = !nfBrQuote;
            else if (!nfBrQuote && c == '\\') i++;
            else if (!nfBrQuote && c == '[') nfBracketDepth++;
            else if (!nfBrQuote && c == ']')
            {
                nfBracketDepth--;
                if (nfBracketDepth < 0) break;
            }

View on GitHub (pinned to 1ced45e900)

Solutions

Shorten the format code to <=255 characters, e.g. by reducing repeated color/locale tokens or splitting conditions across cells.
Audit the code that assembles the format string and cap/bound its length before passing it to the style API.
Run the project's schema validator on the format before write to surface the limit earlier.

Example fix

// before
var fmt = string.Join(";", Enumerable.Repeat("[Red]0.00", 80)); // >255 chars
style.NumberFormat = fmt;
// after
var fmt = string.Join(";", new[]{ "[Red]0.00", "[Blue]-0.00" }); // <=255
style.NumberFormat = fmt;

Defensive patterns

Strategy: validation

Validate before calling

static void AssertFormatLength(string fmt)
{
    if (fmt is null) return;
    if (fmt.Length > 255)
        throw new ArgumentOutOfRangeException(nameof(fmt), $"number format is {fmt.Length} chars; limit is 255.");
}

Try / catch

try { ApplyNumberFormat(fmt); }
catch (ArgumentException ex) when (ex.Message.Contains("Excel's limit is 255"))
{ /* truncate or reject the format */ }

Prevention

Bound any generated/concatenated format string to 255 chars before writing.
Run the schema validator on formats in your test suite.

When it happens

Trigger: Calling an Excel styling API that sets a custom number format (e.g. style numberFormat="...") with a formatCode string longer than 255 characters. The check fires after the section-count (>4) guard and before the bracket-balance check in the format validator.

Common situations: Programmatically concatenating many repeated color/condition sections into one format string; building a format from a template/loop without truncation; pasting a long format copied from another tool.

Related errors

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