PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Sheet code name cannot be empty.

Error message

Sheet code name cannot be empty.

What it means

Thrown by Worksheet::checkSheetCodeName() (via setCodeName(), when validation is enabled) when the code name string has zero characters. A worksheet's code name is written into the xlsx XML as sheet codeName, and Excel rejects empty values, so the library fails fast. Note setCodeName() converts spaces to underscores but cannot rescue an empty string.

Source

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

     * @return string[]
     */
    public static function getInvalidCharacters(): array
    {
        return self::INVALID_CHARACTERS;
    }

    /**
     * Check sheet code name for valid Excel syntax.
     *
     * @param string $sheetCodeName The string to check
     *
     * @return string The valid string
     */
    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;
    }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Provide a non-empty code name, e.g. $sheet->setCodeName('Sheet1_Code')
2. Or simply do not call setCodeName — the writer generates one from the title when none is set
3. Default the value: $sheet->setCodeName($codeName !== '' ? $codeName : $sheet->getTitle())

Example fix

// before
$sheet->setCodeName(trim($request->get('codeName'))); // '' when field empty

// after
$codeName = trim($request->get('codeName'));
$sheet->setCodeName($codeName !== '' ? $codeName : 'Sheet_' . $sheetIndex);

if ($codeName === '') {
    $codeName = 'Sheet_' . $sheetIndex;
}
$sheet->setCodeName($codeName);

When it happens

Trigger: $sheet->setCodeName(''); passing a trimmed user input that is '' ; calling setCodeName($var) where $var was initialized but never assigned. (Readers pass validate=false, so this comes from userland calls.)

Common situations: Deriving code names from optional user/profile fields that can be empty; refactorings that moved the setCodeName call before the variable is populated.

Related errors

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

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