PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Outline level must range between 0 and 7.

Error message

Outline level must range between 0 and 7.

What it means

Excel rows and columns can be grouped into an outline with at most eight levels (0-7); the XLSX format stores only 3 bits for the level. Dimension::setOutlineLevel(), shared by RowDimension and ColumnDimension, enforces that contract and throws for any level below 0 or above 7.

Source

Thrown at src/PhpSpreadsheet/Worksheet/Dimension.php:77

    /**
     * Get Outline Level.
     */
    public function getOutlineLevel(): int
    {
        return $this->outlineLevel;
    }

    /**
     * Set Outline Level.
     * Value must be between 0 and 7.
     *
     * @return $this
     */
    public function setOutlineLevel(int $level)
    {
        if ($level < 0 || $level > 7) {
            throw new PhpSpreadsheetException('Outline level must range between 0 and 7.');
        }

        $this->outlineLevel = $level;

        return $this;
    }

    /**
     * Get Collapsed.
     */
    public function getCollapsed(): bool
    {
        return $this->collapsed;
    }

    /**
     * Set Collapsed.
     *

View on GitHub (pinned to 65b080eef4)

Solutions

1. Clamp the value before setting: setOutlineLevel(max(0, min(7, $level))).
2. Cap the recursion depth of your grouping logic at 7, or flatten deeper nodes onto level 7.
3. Validate the 0-7 range where the value enters your code (form, config, import file).

Example fix

// before
$sheet->getRowDimension($row)->setOutlineLevel($nodeDepth); // throws when $nodeDepth > 7

// after
$sheet->getRowDimension($row)->setOutlineLevel(max(0, min(7, $nodeDepth)));

$level = max(0, min(7, (int) $level));
$sheet->getRowDimension($row)->setOutlineLevel($level);

function isValidOutlineLevel(int $level): bool
{
    return $level >= 0 && $level <= 7;
}

try {
    $dimension->setOutlineLevel($level);
} catch (PhpSpreadsheetException $e) {
    $dimension->setOutlineLevel(7); // flatten deepest level onto the Excel ceiling
}

When it happens

Trigger: $sheet->getRowDimension(5)->setOutlineLevel(8); $sheet->getColumnDimension('D')->setOutlineLevel(-1); a recursive grouping loop that calls setOutlineLevel($depth) on arbitrarily deep hierarchies without capping the depth.

Common situations: Generating outline grouping from unbounded hierarchical data (account trees, WBS structures, nested BOMs); porting code that computes level as $parentLevel + 1 and can exceed 7; passing user-supplied or imported depth values straight through.

Related errors

• Unsupported binary comparison operator
• Cloning the calculation engine is not allowed!
• Unsupported numeric binary operation
• Locale file not found
• #VALUE!

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