iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sheet name '{name}': contains forbidden character '{

Error message

Invalid sheet name '{name}': contains forbidden character '{name[hit]}'. Excel rejects any of: \ / ? * : [ ]

What it means

Excel forbids the characters \ / ? * : [ ] in worksheet names because they collide with path separators, wildcard operators, and sheet-name quoting in formulas. The library scans with IndexOfAny over the forbidden array and reports the first hit, so the file stays openable.

Source

Thrown at src/officecli/Handlers/Excel/ExcelHandler.Helpers.Validation.cs:329

            {
                throw new ArgumentException(
                    $"Formula contains out-of-range cell reference '{m.Value}'. " +
                    "Excel limits: rows 1-1048576, columns A-XFD.");
            }
        }
    }

    internal static void ValidateSheetName(string name)
    {
        if (string.IsNullOrWhiteSpace(name))
            throw new ArgumentException("Invalid sheet name: name cannot be empty or whitespace.");
        if (name.Length > 31)
            throw new ArgumentException(
                $"Invalid sheet name '{name}': length {name.Length} exceeds Excel's 31-char limit.");
        var forbidden = new[] { '\\', '/', '?', '*', ':', '[', ']' };
        var hit = name.IndexOfAny(forbidden);
        if (hit >= 0)
            throw new ArgumentException(
                $"Invalid sheet name '{name}': contains forbidden character '{name[hit]}'. Excel rejects any of: \\ / ? * : [ ]");
        if (name.StartsWith('\'') || name.EndsWith('\''))
            throw new ArgumentException(
                $"Invalid sheet name '{name}': cannot start or end with an apostrophe (').");
        if (name.Equals("History", StringComparison.OrdinalIgnoreCase))
            throw new ArgumentException(
                "Invalid sheet name 'History': reserved by Excel for the change-history sheet.");
    }

    /// <summary>
    /// R35-3: cross-workbook cell formulas like "=[Other.xlsx]Sheet1!A1" or
    /// "=[1]Sheet1!A1" need an externalLinks part to resolve. Without one,
    /// Excel opens the file but the formula shows #REF!. Reject up-front
    /// rather than silently persist a broken formula.
    /// CONSISTENCY(cross-workbook-ref): mirrors the namedrange refersTo
    /// guard in ExcelHandler.Add.Tables.cs (R27-1).
    /// </summary>
    internal static void RejectCrossWorkbookFormula(string formula)

View on GitHub (pinned to 1ced45e900)

Solutions

Strip or replace the forbidden characters (e.g. replace '/' with '-' or '_').
Run a sanitize helper over user input before passing to AddSheet.
Avoid reusing file paths or date strings verbatim as sheet names.

Example fix

// before
wb.AddSheet("2026/03/report");   // contains '/'

// after
static string SanitizeSheetName(string s) {
    var set = new HashSet<char>("\\/?*:[");
    set.Add(']');
    return new string(s.Select(c => set.Contains(c) ? '_' : c).ToArray());
}
wb.AddSheet(SanitizeSheetName("2026/03/report"));   // "2026_03_report"

Defensive patterns

Strategy: validation

Validate before calling

static readonly char[] SheetForbidden = { '\\', '/', '?', '*', ':', '[', ']' };
static string SanitizeSheetName(string n) {
    var hit = n.IndexOfAny(SheetForbidden);
    return hit < 0 ? n : new string(n.Select(c => SheetForbidden.Contains(c) ? '_' : c).ToArray());
}

Try / catch

try { wb.AddSheet(name); }
catch (ArgumentException ex) when (ex.Message.Contains("forbidden character")) {
    wb.AddSheet(SanitizeSheetName(name));
}

Prevention

Always sanitize names derived from filenames, paths, or dates.
Centralize sheet-name sanitization in one helper used by every call site.

When it happens

Trigger: Any sheet name containing one of \ / ? * : [ ]. Common culprits: dates formatted with '/' or ':', file paths used as names, wildcard patterns, bracketed indices.

Common situations: Deriving a sheet name from a filename (e.g. '2026/03/data.csv'); embedding a date '2026:03:01'; using a regex or glob pattern as a label; copying a name from a URL.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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