iOfficeAI/OfficeCLI · error · ArgumentException

Unknown table style: '{styleName}'. Use a built-in name like

Error message

Unknown table style: '{styleName}'. Use a built-in name like 'TableStyleMedium2', or register a custom style on the workbook first.

What it means

Thrown by ValidateTableStyleName when the requested style is not a built-in Excel table/pivot style (TableStyleLight1..28, TableStyleMedium1..28, TableStyleDark1..28, PivotStyle*, TableStyleNone) and is not registered as a custom table style under <x:tableStyles> on the workbook's stylesheet. The library rejects unknown names at add-time rather than letting Excel fail later.

Source

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

                       m.Groups[1].Value.Substring(1).ToLowerInvariant();
            return $"TableStyle{tier}{n}";
        }
        return styleName;
    }

    internal void ValidateTableStyleName(string? styleName)
    {
        if (string.IsNullOrEmpty(styleName)) return;
        if (_builtInTableStyles.Contains(styleName)) return;
        // Workbook-level customStyles live under <x:tableStyles> on the stylesheet.
        var styles = _doc.WorkbookPart?.WorkbookStylesPart?.Stylesheet;
        var tableStyles = styles?.GetFirstChild<TableStyles>();
        if (tableStyles != null)
        {
            foreach (var ts in tableStyles.Elements<TableStyle>())
                if (ts.Name?.Value == styleName) return;
        }
        throw new ArgumentException(
            $"Unknown table style: '{styleName}'. Use a built-in name like " +
            $"'TableStyleMedium2', or register a custom style on the workbook first.");
    }
}

View on GitHub (pinned to 1ced45e900)

Solutions

1. For built-in styles, use the full canonical name (e.g. 'TableStyleMedium2') or run NormalizeTableStyleName first to expand short aliases.
2. For custom styles, register the style under <x:tableStyles> on the stylesheet before referencing it.
3. Check the built-in list (Light/Medium/Dark tiers, 1..28) for typos.

Example fix

// before
string style = "medium2"; // short alias, not accepted directly
// after
string style = "TableStyleMedium2"; // full canonical name
// or normalize first:
string style = NormalizeTableStyleName("medium2"); // → "TableStyleMedium2"

// Validate a style name before use
static readonly HashSet<string> BuiltIns = BuildBuiltInTableStyles();
static bool IsKnownStyle(SpreadsheetDocument doc, string style)
{
    if (BuiltIns.Contains(style)) return true;
    var ts = doc?.WorkbookPart?.WorkbookStylesPart?.Stylesheet?.GetFirstChild<TableStyles>();
    return ts?.Elements<TableStyle>().Any(t => t.Name?.Value == style) == true;
}

null

try { ValidateTableStyleName(style); }
catch (ArgumentException ex) when (ex.Message.StartsWith("Unknown table style"))
{ style = NormalizeTableStyleName(style) ?? "TableStyleMedium2"; /* fall back to a built-in */ }

When it happens

Trigger: Calling an add-table or style API with styleName='MyCustomStyle' when that style is not defined in the workbook; a typo like 'TableStyleMeduim2'; a short alias that was not normalized first (the validator expects the full 'TableStyleX' form unless NormalizeTableStyleName is called beforehand).

Common situations: Typos in built-in names; referencing a custom style that was never registered; using a short alias ('medium2') without running it through NormalizeTableStyleName first.

Related errors

• Table index {tableIndex} out of range (1..{tableParts.Count}
• Table name '{name}' is not a valid Excel name: use letters,
• Invalid '{propertyName}' value '{value}'. Expected a non-neg
• Invalid color value: '{value}'. Expected 6-digit hex RGB (e.
• Invalid source range: {sourceRef}

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