What causes "Invalid index for setting print range." in PHPOffice/PhpSpreadsheet?

Use index 0 to replace the entire print area instead of a specific slot.

PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Invalid index for setting print range.

Error message

Invalid index for setting print range.

What it means

With method 'O' (overwrite, the default), setPrintArea($value, $index) replaces the Nth existing range. When no print area exists yet, any index is coerced to 0; otherwise a negative index is converted (count - abs(index) + 1) and the final index must land in 1..count, or 'Invalid index for setting print range.' is thrown.

Source

Thrown at src/PhpSpreadsheet/Worksheet/PageSetup.php:679

            throw new PhpSpreadsheetException('Cell coordinate must be a range of cells.');
        } elseif (str_contains($value, '$')) {
            throw new PhpSpreadsheetException('Cell coordinate must not be absolute.');
        }
        $value = strtoupper($value);
        if (!$this->printArea) {
            $index = 0;
        }

        if ($method == self::SETPRINTRANGE_OVERWRITE) {
            if ($index == 0) {
                $this->printArea = $value;
            } else {
                $printAreas = explode(',', (string) $this->printArea);
                if ($index < 0) {
                    $index = count($printAreas) - abs($index) + 1;
                }
                if (($index <= 0) || ($index > count($printAreas))) {
                    throw new PhpSpreadsheetException('Invalid index for setting print range.');
                }
                $printAreas[$index - 1] = $value;
                $this->printArea = implode(',', $printAreas);
            }
        } elseif ($method == self::SETPRINTRANGE_INSERT) {
            if ($index == 0) {
                $this->printArea = $this->printArea ? ($this->printArea . ',' . $value) : $value;
            } else {
                $printAreas = explode(',', (string) $this->printArea);
                if ($index < 0) {
                    $index = (int) abs($index) - 1;
                }
                if ($index > count($printAreas)) {
                    throw new PhpSpreadsheetException('Invalid index for setting print range.');
                }
                $printAreas = array_merge(array_slice($printAreas, 0, $index), [$value], array_slice($printAreas, $index));
                $this->printArea = implode(',', $printAreas);
            }

View on GitHub (pinned to 65b080eef4)

Solutions

Use index 0 to replace the entire print area instead of a specific slot.
Count existing ranges first and clamp: $count = count(explode(',', $ps->getPrintArea())); keep 1 <= $index <= $count.
For negative indexes, verify count - abs($index) + 1 lands within 1..count before calling.

Example fix

// before
$ps->setPrintArea('A1:D10', 5); // only 2 ranges exist

// after
$count = $ps->getPrintArea() === '' ? 0 : count(explode(',', $ps->getPrintArea()));
$ps->setPrintArea('A1:D10', $index >= 1 && $index <= $count ? $index : 0);

Defensive patterns

Strategy: validation

Validate before calling

$ps = $sheet->getPageSetup();
$count = $ps->getPrintArea() === '' ? 0 : count(explode(',', $ps->getPrintArea()));
if ($index !== 0 && ($index < 1 || $index > $count)) {
    $index = 0; // overwrite the whole print area instead of a specific slot
}
$ps->setPrintArea($range, $index, PageSetup::SETPRINTRANGE_OVERWRITE);

Try / catch

try {
    $ps->setPrintArea($range, $index);
} catch (PhpSpreadsheetException $e) {
    $ps->setPrintArea($range); // fall back to full overwrite (index 0)
}

Prevention

Index 0 replaces the whole print area — prefer it over positional slots
Negative indexes convert to count - abs(n) + 1 and must still land in 1..count
With no existing print area any index is coerced to 0, hiding bad values until one exists

When it happens

Trigger: setPrintArea('A1:D10', 5) when only 2 ranges exist; setPrintArea('A1:D10', -10) with 2 ranges (2 - 10 + 1 = -7, below 1); assuming out-of-range positive indexes append — they do not, index 0 does.

Common situations: Index values taken from user input or config; list sizes that changed between versions; negative-index arithmetic misjudged (it counts from the end).

Related errors

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