PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Workbook already contains a worksheet named '{$worksheet->ge

Error message

Workbook already contains a worksheet named '{$worksheet->getTitle()}'. Rename this worksheet first.

What it means

Spreadsheet::addSheet() inserts a Worksheet into the workbook and enforces unique sheet titles. Auto-renaming only happens when you pass the third argument $retitleIfNeeded = true (as duplicateWorksheetByTitle() does); by default a colliding title throws. Sheet titles are the workbook's key namespace, so duplicates would corrupt the file on save.

Source

Thrown at src/PhpSpreadsheet/Spreadsheet.php:631

     * @param Worksheet $worksheet The worksheet to add
     * @param null|int $sheetIndex Index where sheet should go (0,1,..., or null for last)
     */
    public function addSheet(Worksheet $worksheet, ?int $sheetIndex = null, bool $retitleIfNeeded = false): Worksheet
    {
        if ($retitleIfNeeded) {
            $title = $worksheet->getTitle();
            if ($this->sheetNameExists($title)) {
                $i = 1;
                $newTitle = "$title $i";
                while ($this->sheetNameExists($newTitle)) {
                    ++$i;
                    $newTitle = "$title $i";
                }
                $worksheet->setTitle($newTitle);
            }
        }
        if ($this->sheetNameExists($worksheet->getTitle())) {
            throw new Exception(
                "Workbook already contains a worksheet named '{$worksheet->getTitle()}'. Rename this worksheet first."
            );
        }

        if ($sheetIndex === null) {
            if ($this->activeSheetIndex < 0) {
                $this->activeSheetIndex = 0;
            }
            $this->workSheetCollection[] = $worksheet;
        } else {
            // Insert the sheet at the requested index
            array_splice(
                $this->workSheetCollection,
                $sheetIndex,
                0,
                [$worksheet]
            );

View on GitHub (pinned to 65b080eef4)

Solutions

1. Check uniqueness first: if ($spreadsheet->sheetNameExists($title)) pick another title before addSheet().
2. Pass true as the third argument: $spreadsheet->addSheet($sheet, null, true) to auto-rename to 'Title 1', 'Title 2', ...
3. Rename the incoming sheet before adding: $sheet->setTitle($uniqueTitle);
4. Rename or remove the pre-existing sheet: $spreadsheet->removeSheetByIndex($spreadsheet->getIndex($existingSheet));

Example fix

// before
$spreadsheet->addSheet($sheet); // throws if 'Report' exists

// after
if ($spreadsheet->sheetNameExists($sheet->getTitle())) {
    $sheet->setTitle($sheet->getTitle() . ' ' . uniqid());
}
$spreadsheet->addSheet($sheet);
// or simply: $spreadsheet->addSheet($sheet, null, true);

if ($spreadsheet->sheetNameExists($sheet->getTitle())) {
    $sheet->setTitle(uniqueTitle($sheet->getTitle(), $spreadsheet));
}
$spreadsheet->addSheet($sheet);

function uniqueTitle(string $base, \PhpOffice\PhpSpreadsheet\Spreadsheet $s): string
{
    $i = 1;
    while ($s->sheetNameExists("$base $i")) { ++$i; }
    return "$base $i";
}

function canAddSheetWithTitle(\PhpOffice\PhpSpreadsheet\Spreadsheet $s, string $title): bool
{
    return !$s->sheetNameExists($title);
}

try {
    $spreadsheet->addSheet($sheet);
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    $sheet->setTitle($sheet->getTitle() . ' ' . uniqid());
    $spreadsheet->addSheet($sheet);
}

When it happens

Trigger: Calling $spreadsheet->addSheet($sheet) where $sheet->getTitle() already matches a sheet in that workbook: e.g. addSheet(new Worksheet($spreadsheet, 'Report')) while 'Report' exists; re-adding a sheet you removed earlier without renaming; inserting a sheet built from a template with a fixed title into the same workbook twice.

Common situations: Template-based generators that stamp a constant name like 'Data' or 'Sheet1' per iteration; merging two workbooks sheet-by-sheet with addSheet() instead of addExternalSheet(); loops that create sheets from user-supplied names without uniquifying.

Related errors

• Workbook already contains a worksheet named '{$worksheet->ge
• Cannot update when cell is not bound to a worksheet
• Cannot get column when cell is not bound to a worksheet
• Cannot get row when cell is not bound to a worksheet
• Cannot check for data validation when cell is not bound to a

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