What causes "Invalid sheet name: name cannot be empty or whitespace." in iOfficeAI/OfficeCLI?

Pass a non-empty, trimmed name.

iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sheet name: name cannot be empty or whitespace.

Error message

Invalid sheet name: name cannot be empty or whitespace.

What it means

ValidateSheetName was called with null, empty, or whitespace-only input. Excel requires every worksheet to carry a non-empty name, so the library rejects the value before it can reach the OOXML writer. This is the first guard in the sheet-name validation chain.

Source

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

            var col = m.Groups[1].Value.ToUpperInvariant();
            if (!long.TryParse(m.Groups[2].Value, out var row)) continue;
            // Column index check: ColumnNameToIndex would throw on overflow,
            // but we want a clean validation message. Compute manually.
            int colIdx = 0;
            foreach (var ch in col) colIdx = colIdx * 26 + (ch - 'A' + 1);
            if (colIdx < 1 || colIdx > 16384 || row < 1 || row > 1048576)
            {
                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

View on GitHub (pinned to 1ced45e900)

Solutions

Pass a non-empty, trimmed name.
Default to a generated unique name (e.g. 'Sheet1', 'Sheet2') when the source value is blank.
Guard at the input boundary so blank never reaches the sheet API.

Example fix

// before
wb.AddSheet(userTitle.Trim());   // userTitle was all spaces -> ""

// after
var name = string.IsNullOrWhiteSpace(userTitle) ? $"Sheet{wb.SheetCount+1}" : userTitle.Trim();
wb.AddSheet(name);

Defensive patterns

Strategy: validation

Validate before calling

static string EnsureSheetName(string? raw, int fallbackIndex) {
    var n = (raw ?? string.Empty).Trim();
    return string.IsNullOrWhiteSpace(n) ? $"Sheet{fallbackIndex}" : n;
}

Try / catch

try { wb.AddSheet(name); }
catch (ArgumentException ex) when (ex.Message.Contains("cannot be empty")) {
    name = $"Sheet{wb.SheetCount + 1}";
    wb.AddSheet(name);
}

Prevention

Never pass user input straight to AddSheet; route it through a normalizer.
Treat blank as 'generate a default', not as 'throw'.

When it happens

Trigger: Any API that creates or renames a sheet (AddSheet, rename, copy/move target) receiving string.Empty, " ", or null. The string.IsNullOrWhiteSpace check trips before length/character checks run.

Common situations: User input field left blank; a variable never assigned; a .Trim() that reduced the value to empty; reading a name from config that was omitted.

Related errors

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