iOfficeAI/OfficeCLI · error · ArgumentException

Invalid sheet name '{name}': length {name.Length} exceeds Ex

Error message

Invalid sheet name '{name}': length {name.Length} exceeds Excel's 31-char limit.

What it means

Excel caps worksheet names at 31 characters. The library enforces this at validation time (name.Length > 31) so the resulting workbook can be opened by real Excel without a repair prompt. Longer names are a hard OOXML/schema constraint, not a soft preference.

Source

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

            // 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
    /// "=[1]Sheet1!A1" need an externalLinks part to resolve. Without one,
    /// Excel opens the file but the formula shows #REF!. Reject up-front

View on GitHub (pinned to 1ced45e900)

Solutions

1. Truncate or abbreviate the name to <= 31 characters.
2. If the full name matters, store it in a cell or a custom property instead of the sheet tab.
3. Validate length at the UI boundary and show the limit to the user.

Example fix

// before
wb.AddSheet("Quarterly Financial Summary by Region and Product Line 2026");

// after
var name = longName.Length > 31 ? longName.Substring(0, 31) : longName;
wb.AddSheet(name);

const int MaxSheetNameLen = 31;
static string ClampSheetName(string n) =>
    n.Length <= MaxSheetNameLen ? n : n.Substring(0, MaxSheetNameLen);

try { wb.AddSheet(name); }
catch (ArgumentException ex) when (ex.Message.Contains("31-char limit")) {
    wb.AddSheet(name.Substring(0, 31));
}

When it happens

Trigger: AddSheet or rename with a string longer than 31 chars. The length check runs after the empty/whitespace guard, so a 32+ char non-blank name trips here.

Common situations: User-supplied titles; auto-generated names from file metadata or headers; localized names that expanded in translation; concatenated identifiers.

Related errors

• Property 'sqref' (or 'range'/'ref') is required for validati
• Invalid sheet name: name cannot be empty or whitespace.
• Invalid sheet name '{name}': contains forbidden character '{
• Invalid sheet name '{name}': cannot start or end with an apo
• Invalid sheet name 'History': reserved by Excel for the chan

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