iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sheet 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.

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.

Appendix: 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)