iOfficeAI/OfficeCLI · error · ArgumentException

Table name '{name}' is not a valid Excel name: use letters,

Error message

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.

What it means

Thrown by the table-name validator (userProvided=true) when the name fails Excel's defined-name grammar: identifier chars only (Unicode letters, digits, '.', '_'), must start with a letter or '_'. Excel accepts CJK/Cyrillic table names. Spaces, hyphens, and other punctuation pass schema validation but real Excel refuses the whole file (0x800A03EC).

Source

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

            // 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}_'.");
            return name;
        }
        var looksLikeRef = LooksLikeCellReference(name)
            || System.Text.RegularExpressions.Regex.IsMatch(name, @"^[0-9]+$");
        return looksLikeRef ? name + "_" : name;
    }

    // T6 — built-in Excel table style names. Unknown names are rejected at
    // Add time rather than silently passed through to Excel.
    private static readonly HashSet<string> _builtInTableStyles = BuildBuiltInTableStyles();
    private static HashSet<string> BuildBuiltInTableStyles()

View on GitHub (pinned to 1ced45e900)

Solutions

1. Strip/replace disallowed characters: spaces → '_', hyphens → '_' or remove.
2. Ensure the first character is a Unicode letter or '_'.
3. Use the validationCode regex before submitting the name.

Example fix

// before
string name = "Q1 Sales Data"; // spaces → rejected
// after
string name = "Q1_Sales_Data";
// or sanitize programmatically:
string name = new string(header.Where(c => char.IsLetterOrDigit(c) || c == '_' || c == '.').ToArray());
if (name.Length == 0 || char.IsDigit(name[0])) name = "_" + name;

// Validate against Excel's defined-name grammar
static bool IsValidTableName(string name)
    => !string.IsNullOrEmpty(name)
       && System.Text.RegularExpressions.Regex.IsMatch(name, @"^[\p{L}_\\][\p{L}\p{N}._\\]*$");

null

try { /* add table */ }
catch (ArgumentException ex) when (ex.Message.Contains("is not a valid Excel name"))
{ name = System.Text.RegularExpressions.Regex.Replace(name, "[^\\p{L}\\p{N}._]", "_"); if (char.IsDigit(name[0])) name = "_" + name; }

When it happens

Trigger: Calling an add-table API with a name containing spaces ('Sales Data'), hyphens ('Q1-Data'), leading digit ('1stTable'), or other disallowed punctuation.

Common situations: User-supplied table names from form fields; generating names from headers that contain spaces or symbols; copying column headers verbatim as table names.

Related errors

• pivot name must not be empty
• Table index {tableIndex} out of range (1..{tableParts.Count}
• Table name '{name}' matches Excel's internal Tbl{{N}} naming
• Table name '{name}' looks like a cell reference; Excel refus
• Unknown table style: '{styleName}'. Use a built-in name like

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