PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Invalid character found in sheet code name

Error message

Invalid character found in sheet code name

What it means

Thrown by Worksheet::checkSheetCodeName() when the code name contains any of the characters * : / \ ? [ ] (self::INVALID_CHARACTERS) or begins/ends with a single quote. Excel forbids these in sheet code names, and unlike spaces (which setCodeName converts to underscores) these characters are not auto-repaired, so the library throws.

Source

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

     * 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;
    }

    /**
     * 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

View on GitHub (pinned to 65b080eef4)

Solutions

1. Sanitize before setting: str_replace(['*','/',':','\\','?','[',']'], '_', $codeName) and trim surrounding quotes
2. Prefer letting the library derive the code name from the (already validated) title instead of setting it manually
3. Apply the same character policy you use for titles to code names, plus the no-leading/trailing-quote rule

Example fix

// before
$sheet->setCodeName('Sales/Europe 2024'); // '/' is invalid

// after
$clean = str_replace(['*','/',':','\\','?','[',']'], '_', 'Sales/Europe 2024');
$sheet->setCodeName($clean); // 'Sales_Europe_2024' (space -> '_' automatically)

const INVALID = ['*', '/', ':', '\\', '?', '[', ']'];

$codeName = str_replace(INVALID, '_', trim($codeName, "'\""));
if ($codeName !== '') {
    $sheet->setCodeName($codeName);
}

When it happens

Trigger: $sheet->setCodeName('Sales/2024'); setCodeName("'TopSheet'") with surrounding apostrophes; passing a title containing ? or [ unchanged as the code name.

Common situations: Reusing a date-bearing title like 'Report 2024/06' as code name; importing names from external systems (file paths, slashes) into code names; generating code names from free-text fields.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

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