PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Maximum 31 characters allowed in sheet title.

Error message

Maximum 31 characters allowed in sheet title.

What it means

Thrown by Worksheet::checkSheetTitle() (via setTitle()) when the title exceeds self::SHEET_TITLE_MAXIMUM_LENGTH, which is 31 characters (counted multibyte-safely via StringHelper). Excel's tab-name limit is 31 chars, and PhpSpreadsheet enforces it rather than truncating silently.

Source

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

    }

    /**
     * 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');
        }

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

        return $sheetTitle;
    }

    /**
     * Get a sorted list of all cell coordinates currently held in the collection by row and column.
     *
     * @param bool $sorted Also sort the cell collection?
     *
     * @return string[]
     */
    public function getCoordinates(bool $sorted = true): array
    {
        if (!isset($this->cellCollection)) { //* @phpstan-ignore isset.initializedProperty (may be null at destruct time)
            return [];
        }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Truncate multibyte-safely: $sheet->setTitle(mb_substr($title, 0, 31))
2. Validate length where the title enters your code: if (mb_strlen($title) > 31) shorten it deterministically (e.g. ellipsize)
3. Keep a fixed short prefix plus a counter for generated sheets ('Report_1', 'Report_2')

Example fix

// before
$sheet->setTitle('Consolidated Revenue Overview for Fiscal Year 2024 - EU Region'); // > 31 chars

// after
$title = 'Consolidated Revenue Overview for Fiscal Year 2024 - EU Region';
$sheet->setTitle(mb_substr($title, 0, 31));

$title = mb_substr($title, 0, 31);
$sheet->setTitle($title);

When it happens

Trigger: $sheet->setTitle('Very Long Descriptive Report Name ...') over 31 chars; setTitle($userProvidedName) with unconstrained input; also hits createSheet()->setTitle() chains in report generators.

Common situations: Report/export generators building titles from entity names + dates; localized (CJK/accented) names where byte length differs from character length; iterating versions of a name until one fits but forgetting the length cap.

Related errors

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

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