PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Tab ratio must be between 0 and 1000.

Error message

Tab ratio must be between 0 and 1000.

What it means

Spreadsheet::setTabRatio(int) sets the ratio of the sheet-tab bar to the horizontal scroll bar, expressed out of 1000 (it maps to Excel's tabRatio workbook-view property). Only values in the closed range 0..1000 are accepted; anything outside throws 'Tab ratio must be between 0 and 1000.'

Source

Thrown at src/PhpSpreadsheet/Spreadsheet.php:1706

     * @return int Ratio between the workbook tabs bar and the horizontal scroll bar
     */
    public function getTabRatio(): int
    {
        return $this->tabRatio;
    }

    /**
     * Set the ratio between the workbook tabs bar and the horizontal scroll bar
     * TabRatio is assumed to be out of 1000 of the horizontal window width.
     *
     * @param int $tabRatio Ratio between the tabs bar and the horizontal scroll bar
     */
    public function setTabRatio(int $tabRatio): void
    {
        if ($tabRatio >= 0 && $tabRatio <= 1000) {
            $this->tabRatio = (int) $tabRatio;
        } else {
            throw new Exception('Tab ratio must be between 0 and 1000.');
        }
    }

    public function reevaluateAutoFilters(bool $resetToMax): void
    {
        foreach ($this->workSheetCollection as $sheet) {
            $filter = $sheet->getAutoFilter();
            if (!empty($filter->getRange())) {
                if ($resetToMax) {
                    $filter->setRangeToMaxRow();
                }
                $filter->showHideRows();
            }
        }
    }

    /**
     * @throws Exception

View on GitHub (pinned to 65b080eef4)

Solutions

1. Rescale percentages: setTabRatio((int) round($percent * 10));
2. Clamp before calling: $ratio = max(0, min(1000, $ratio));
3. Validate config/UI input against the 0..1000 range and reject early with a clear message.

Example fix

// before
$spreadsheet->setTabRatio(60); // meant 60% but throws nothing... wrong scale
$spreadsheet->setTabRatio(1500); // throws

// after
$percent = 60;
$spreadsheet->setTabRatio(max(0, min(1000, (int) round($percent * 10)))); // 600 = 60%

$ratio = max(0, min(1000, (int) $ratio)); // clamp to 0..1000
$spreadsheet->setTabRatio($ratio);

function isValidTabRatio(int $r): bool
{
    return $r >= 0 && $r <= 1000;
}

try {
    $spreadsheet->setTabRatio($ratio);
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    $spreadsheet->setTabRatio(600); // 60%, a safe default
}

When it happens

Trigger: setTabRatio(100) meaning '100%' then later passing a 0-1 float cast to int (0); setTabRatio(1200); accepting a percentage from user input (0-100 scale) without rescaling to 0-1000; arithmetic that can go negative.

Common situations: Confusion between percent (0-100) and Excel's per-mille scale (0-1000); UI sliders that emit 0-100 directly; config values inherited from another library using a different scale.

Related errors

• First sheet index must be a positive integer.
• Invalid visibility value.
• Text rotation {$angleInDegrees} should be a value between -9
• {$range} is an invalid range for AutoFilter
• #VALUE!

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