PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

CellStyleXf index is out of bounds.

Error message

CellStyleXf index is out of bounds.

What it means

Spreadsheet::removeCellStyleXfByIndex(int) deletes one entry from the cellStyleXf collection (the named 'cell styles' like the styles dropdown in Excel, distinct from cellXfs). It throws 'CellStyleXf index is out of bounds.' when the index exceeds count-1. This is a low-level maintenance API on a collection most user code never touches.

Source

Thrown at src/PhpSpreadsheet/Spreadsheet.php:1419

    /**
     * Add a cellStyleXf to the workbook.
     */
    public function addCellStyleXf(Style $style): void
    {
        $this->cellStyleXfCollection[] = $style;
        $style->setIndex(count($this->cellStyleXfCollection) - 1);
    }

    /**
     * Remove cellStyleXf by index.
     *
     * @param int $cellStyleIndex Index to cellXf
     */
    public function removeCellStyleXfByIndex(int $cellStyleIndex): void
    {
        if ($cellStyleIndex > count($this->cellStyleXfCollection) - 1) {
            throw new Exception('CellStyleXf index is out of bounds.');
        }
        array_splice($this->cellStyleXfCollection, $cellStyleIndex, 1);
    }

    /**
     * Eliminate all unneeded cellXf and afterwards update the xfIndex for all cells
     * and columns in the workbook.
     */
    public function garbageCollect(): void
    {
        // how many references are there to each cellXf ?
        $countReferencesCellXf = [];
        foreach ($this->cellXfCollection as $index => $cellXf) {
            $countReferencesCellXf[$index] = 0;
        }

        foreach ($this->getWorksheetIterator() as $sheet) {
            // from cells

View on GitHub (pinned to 65b080eef4)

Solutions

1. Validate against the correct collection: if ($i >= 0 && $i < count($spreadsheet->getCellStyleXfCollection())) ...
2. Prefer $spreadsheet->garbageCollect() for pruning unused styles.
3. Iterate downward when removing multiple entries.
4. Confirm you actually mean cellStyleXf (named styles) and not cellXf (per-cell formatting).

Example fix

// before
$spreadsheet->removeCellStyleXfByIndex($i); // $i beyond collection end

// after
$max = count($spreadsheet->getCellStyleXfCollection()) - 1;
if ($i >= 0 && $i <= $max) {
    $spreadsheet->removeCellStyleXfByIndex($i);
}

if ($cellStyleIndex >= 0 && $cellStyleIndex < count($spreadsheet->getCellStyleXfCollection())) {
    $spreadsheet->removeCellStyleXfByIndex($cellStyleIndex);
}

function isValidCellStyleXfIndex(\PhpOffice\PhpSpreadsheet\Spreadsheet $s, int $i): bool
{
    return $i >= 0 && $i < count($s->getCellStyleXfCollection());
}

try {
    $spreadsheet->removeCellStyleXfByIndex($i);
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    error_log('cellStyleXf removal skipped: ' . $e->getMessage());
}

When it happens

Trigger: removeCellStyleXfByIndex($i) with $i >= count($spreadsheet->getCellStyleXfCollection()); off-by-one loops over the styleXf collection; indexes copied from another workbook's collection.

Common situations: Style-cleanup tooling written against the wrong collection (cellXf vs cellStyleXf) assuming equal sizes; scripts pruning template styles after loading themed files; debugging code iterating collections with <= instead of <.

Related errors

• CellXf index is out of bounds.
• Token with id $id does not exist.
• You tried to remove a sheet by the out of bounds index: {$sh
• Your requested sheet index: {$sheetIndex} is out of bounds.
• You tried to set a sheet active by the out of bounds index:

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