PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Maximum 31 characters allowed in sheet code name.

Error message

Maximum 31 characters allowed in sheet code name.

What it means

Thrown by Worksheet::checkSheetCodeName() when the code name exceeds self::SHEET_TITLE_MAXIMUM_LENGTH (31) characters. Excel enforces the same 31-character ceiling on code names as on titles; setCodeName() itself only auto-trims when de-duplicating (down to 29/28/27 to append _N), so a too-long first-time name throws.

Source

Thrown at src/PhpSpreadsheet/Worksheet/Worksheet.php:453

     */
    private static function checkSheetCodeName(string $sheetCodeName): string
    {
        $charCount = StringHelper::countCharacters($sheetCodeName);
        if ($charCount == 0) {
            throw new Exception('Sheet code name cannot be empty.');
        }
        // Some of the printable ASCII characters are invalid:  * : / \ ? [ ] and  first and last characters cannot be a "'"
        if (
            (str_replace(self::INVALID_CHARACTERS, '', $sheetCodeName) !== $sheetCodeName)
            || (StringHelper::substring($sheetCodeName, -1, 1) == '\'')
            || (StringHelper::substring($sheetCodeName, 0, 1) == '\'')
        ) {
            throw new Exception('Invalid character found in sheet code name');
        }

        // Enforce maximum characters allowed for sheet title
        if ($charCount > self::SHEET_TITLE_MAXIMUM_LENGTH) {
            throw new Exception('Maximum ' . self::SHEET_TITLE_MAXIMUM_LENGTH . ' characters allowed in sheet code name.');
        }

        return $sheetCodeName;
    }

    /**
     * Check sheet title for valid Excel syntax.
     *
     * @param string $sheetTitle The string to check
     *
     * @return string The valid string
     */
    private static function checkSheetTitle(string $sheetTitle): string
    {
        // Some of the printable ASCII characters are invalid:  * : / \ ? [ ]
        if (str_replace(self::INVALID_CHARACTERS, '', $sheetTitle) !== $sheetTitle) {
            throw new Exception('Invalid character found in sheet title');
        }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Truncate to at most 31 characters (multibyte-safe): $sheet->setCodeName(mb_substr($codeName, 0, 31))
2. Keep code names short and structural ('Sheet1_Data'), not descriptive sentences
3. Check StringHelper::countCharacters / mb_strlen($codeName) <= 31 before setting

Example fix

// before
$sheet->setCodeName('QuarterlyRegionalSalesReportForAllEuropeanMarkets'); // 54 chars

// after
$sheet->setCodeName(mb_substr('QuarterlyRegionalSalesReportForAllEuropeanMarkets', 0, 31));

$codeName = mb_substr($codeName, 0, 31);
$sheet->setCodeName($codeName);

When it happens

Trigger: $sheet->setCodeName(str_repeat('a', 32)); concatenating department + region + year into a code name that crosses 31 chars; passing a full sentence as code name.

Common situations: Machine-generated identifiers (prefixed UUIDs, long enum labels) used as code names; localized names whose UTF-8 length is misjudged because strlen was used instead of a character count.

Related errors

• Sheet code name cannot be empty.
• Invalid character found in sheet code name
• Maximum 31 characters allowed in sheet title.
• {$range} is an invalid range for AutoFilter
• Invalid character found in sheet title

AI-assisted analysis of PHPOffice/PhpSpreadsheet@65b080eef4 (2026-08-17). Data as JSON: /api/errors/26818d18e4491a58. Report an issue: GitHub.