iOfficeAI/OfficeCLI · error · ArgumentException

Table name '{name}' matches Excel's internal Tbl{{N}} naming

Error message

Table name '{name}' matches Excel's internal Tbl{{N}} naming pattern and is rejected by Mac Excel. Use 'Table{{N}}' (default) or a descriptive name like 'SalesData'.

What it means

Thrown by the table-name validator (userProvided=true) when the name matches ^[Tt][Bb][Ll]\d+$ — Excel's internal table identifier prefix. Mac Excel silently renames such tables with a '_' suffix and shows a 'found a problem' repair dialog on open. Windows Excel auto-recovers silently, masking the issue. The library blocks the pattern up front so users get a clear error.

Source

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

    //
    // When `userProvided` is false (auto-derived default such as
    // `Table{id}`, or tableColumn name read from a header cell) we suffix
    // "_" on cell-reference-shaped names to keep defaults safe.
    internal static string SanitizeTableIdentifier(string? name, bool userProvided = false)
    {
        if (string.IsNullOrEmpty(name)) return "_";
        if (userProvided)
        {
            // Mac Excel rejects the "Tbl{N}" pattern (Excel's internal table
            // identifier prefix), silently renaming with a "_" suffix and
            // triggering "found a problem" repair dialog on open. Block it
            // up front so users get a clear error instead of the repair flow.
            // Windows Excel auto-recovers silently which historically masked
            // this on officeshot Windows-side validation. "Tbl" alone or
            // "Tbl"+letters (e.g. "TblData") are NOT rejected — only the
            // exact Tbl-followed-by-digits pattern collides.
            if (System.Text.RegularExpressions.Regex.IsMatch(name, @"^[Tt][Bb][Ll]\d+$"))
                throw new ArgumentException(
                    $"Table name '{name}' matches Excel's internal Tbl{{N}} naming pattern and is rejected by Mac Excel. Use 'Table{{N}}' (default) or a descriptive name like 'SalesData'.");
            // Excel enforces defined-name grammar on table names: identifier
            // chars only (no spaces), must not parse as an A1/R1C1 cell
            // reference. Violations pass schema validation but real Excel
            // refuses the whole file (0x800A03EC) — reject up front, same
            // rule set as the namedrange validator.
            // "Letter" is any Unicode letter (\p{L}) — Excel accepts CJK/
            // Cyrillic table names (same identifier grammar as defined
            // names, whose validator was widened the same way).
            if (!System.Text.RegularExpressions.Regex.IsMatch(name, @"^[\p{L}_\\][\p{L}\p{N}._\\]*$"))
                throw new ArgumentException(
                    $"Table name '{name}' is not a valid Excel name: use letters, digits, '.' or '_' only, starting with a letter or '_' (no spaces). Excel refuses to open files with other table names.");
            if (LooksLikeCellReference(name)
                || System.Text.RegularExpressions.Regex.IsMatch(name, @"^[Rr]\d+[Cc]\d+$")
                || name.Equals("R", StringComparison.OrdinalIgnoreCase)
                || name.Equals("C", StringComparison.OrdinalIgnoreCase))
                throw new ArgumentException(
                    $"Table name '{name}' looks like a cell reference; Excel refuses to open files with such table names. Choose a name like '{name}_'.");

View on GitHub (pinned to 1ced45e900)

Solutions

1. Use a descriptive name like 'SalesData', or the default 'Table{N}' pattern.
2. Pick a prefix that is not 'Tbl' followed by digits — 'TblData', 'Table1', or any other pattern is fine.
3. If you must use 'Tbl', ensure it is followed by at least one letter, not digits.

Example fix

// before
string name = $"Tbl{n}"; // n=1 → rejected
// after
string name = $"Table{n}";  // 'Table1', 'Table2', ...
// or descriptive:
string name = "SalesData";

// Reject the Tbl{N} pattern before the API call
static bool IsReservedTblName(string name)
    => System.Text.RegularExpressions.Regex.IsMatch(name ?? "", @"^[Tt][Bb][Ll]\d+$");

null

try { /* add table */ }
catch (ArgumentException ex) when (ex.Message.Contains("Tbl"))
{ name = name + "Data"; /* retry with a safe suffix */ }

When it happens

Trigger: Calling an add-table API with name='Tbl1', name='tbl42', name='TBL99', or any name matching Tbl + digits. The pattern Tbl alone or Tbl+letters (e.g. 'TblData') is NOT rejected — only Tbl followed by digits.

Common situations: Auto-generating table names from a counter that uses 'Tbl' prefix; copying Excel's internal naming; user-chosen names that happen to match the pattern.

Related errors

• Table name '{name}' is not a valid Excel name: use letters,
• Table name '{name}' looks like a cell reference; Excel refus
• pivot name must not be empty
• pivot name must not be whitespace-only
• pivot name contains invalid control characters

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