iOfficeAI/OfficeCLI · error · ArgumentException

invalid layout: '{mode}'. Valid: compact, outline, tabular

Error message

invalid layout: '{mode}'. Valid: compact, outline, tabular

What it means

Thrown by PushLayoutMode when the 'layout' property contains a token not in _validLayoutModes {compact, outline, tabular}. These correspond to Excel's three pivot layout report formats. Unknown layout tokens are rejected up front (CONSISTENCY strict-enums) rather than silently defaulting.

Source

Thrown at src/officecli/Core/PivotTableHelper.cs:595

    /// <summary>
    /// Parse layout property into the thread-static scope. Supports:
    ///   layout=compact|outline|tabular
    /// Returns a scope that restores the previous value on Dispose.
    /// </summary>
    private static readonly HashSet<string> _validLayoutModes = new(StringComparer.OrdinalIgnoreCase)
    {
        "compact", "outline", "tabular"
    };

    private static IDisposable PushLayoutMode(Dictionary<string, string> properties)
    {
        var prev = _layoutMode;
        if (properties.TryGetValue("layout", out var mode) && !string.IsNullOrWhiteSpace(mode))
        {
            var normalized = mode.Trim().ToLowerInvariant();
            if (!_validLayoutModes.Contains(normalized))
                throw new ArgumentException(
                    $"invalid layout: '{mode}'. Valid: compact, outline, tabular");
            _layoutMode = normalized;
        }
        return new LayoutModeScope(prev);
    }

    private sealed class LayoutModeScope : IDisposable
    {
        private readonly string? _prev;
        public LayoutModeScope(string? prev) { _prev = prev; }
        public void Dispose() { _layoutMode = _prev; }
    }

    // CONSISTENCY(thread-static-pivot-opts): repeatItemLabels — "Repeat All
    // Item Labels" in Excel's Report Layout menu. When true, outer row axis
    // labels are repeated on every leaf row instead of appearing only once
    // at the top of each group. OOXML: fillDownLabelsDefault on x14:pivotTableDefinition.
    [ThreadStatic] private static bool? _repeatItemLabels;

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use one of: compact, outline, tabular.
2. If unsure which to use, omit the layout property to accept the default (compact).
3. Check spelling — case-insensitive but must exactly match one of the three tokens.

Example fix

// before
Set pivot layout='flat'
// after
Set pivot layout='compact'

var validLayouts = new HashSet<string>(StringComparer.OrdinalIgnoreCase) { "compact", "outline", "tabular" };
if (!string.IsNullOrWhiteSpace(layout) && !validLayouts.Contains(layout.Trim().ToLowerInvariant()))
    throw new ArgumentException($"Invalid layout '{layout}'. Valid: compact, outline, tabular.");

static readonly HashSet<string> ValidLayouts =
    new(StringComparer.OrdinalIgnoreCase) { "compact", "outline", "tabular" };
static bool IsValidLayout(string mode) =>
    string.IsNullOrWhiteSpace(mode) || ValidLayouts.Contains(mode.Trim().ToLowerInvariant());

When it happens

Trigger: Calling Add/Set pivot layout='tabular' is valid, but layout='flat', layout='default', layout='grid', or any token outside the three accepted values triggers this.

Common situations: Using Excel UI terminology that does not match the library's token (e.g. 'flat' instead of 'compact'); typo like layout='oultine'; assuming 'grid' is an alias for 'tabular'.

Related errors

• invalid sort: '{mode}'. Valid: asc, desc, locale, locale-des
• Invalid subtotals '{s}'. Valid: on, off (default on)
• labelFilter type must be one of contains/doesNotContain/begi
• pivot name must not be empty
• labelFilter must be 'field:type:value', got: '{spec}'

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