What causes "You must specify a worksheet or a scope for a Named Range" in PHPOffice/PhpSpreadsheet?

Pass a worksheet, e.g. new NamedRange('Total', $spreadsheet->getActiveSheet())

PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

You must specify a worksheet or a scope for a Named Range

Error message

You must specify a worksheet or a scope for a Named Range

What it means

A NamedRange anchors a defined name to a worksheet, either as its worksheet or as its local scope. The constructor requires at least one of those two; both null throws. Even workbook-global names need a worksheet passed here (scope/locality is then controlled by localOnly/scope).

Source

Thrown at src/PhpSpreadsheet/NamedRange.php:21

namespace PhpOffice\PhpSpreadsheet;

use PhpOffice\PhpSpreadsheet\Cell\Coordinate;
use PhpOffice\PhpSpreadsheet\Worksheet\Worksheet;

class NamedRange extends DefinedName
{
    /**
     * Create a new Named Range.
     */
    public function __construct(
        string $name,
        ?Worksheet $worksheet = null,
        string $range = 'A1',
        bool $localOnly = false,
        ?Worksheet $scope = null
    ) {
        if ($worksheet === null && $scope === null) {
            throw new Exception('You must specify a worksheet or a scope for a Named Range');
        }
        parent::__construct($name, $worksheet, $range, $localOnly, $scope);
    }

    /**
     * Get the range value.
     */
    public function getRange(): string
    {
        return $this->value;
    }

    /**
     * Set the range value.
     */
    public function setRange(string $range): self
    {
        if (!empty($range)) {

View on GitHub (pinned to 65b080eef4)

Solutions

Pass a worksheet, e.g. new NamedRange('Total', $spreadsheet->getActiveSheet())
For sheet-local names pass the scope worksheet (and localOnly=true), which also satisfies the check
Guard null results from getSheetByName()/getSheet() before constructing, and fail with a clearer message about the missing sheet

Example fix

// before
$sheet = $spreadsheet->getSheetByName('Q1 '); // trailing space -> null
$spreadsheet->addNamedRange(new NamedRange('Total', $sheet)); // throws

// after
$sheet = $spreadsheet->getSheetByName(trim($name)) ?? $spreadsheet->getActiveSheet();
$spreadsheet->addNamedRange(new NamedRange('Total', $sheet));

Defensive patterns

Strategy: validation

Validate before calling

$sheet = $worksheet ?? $scope ?? $spreadsheet->getActiveSheet();
$spreadsheet->addNamedRange(new NamedRange($name, $sheet, $range, $localOnly));

Prevention

Never rely on getSheetByName() succeeding — null-coalesce to a fallback sheet or fail with your own message
Remember even workbook-global named ranges need a worksheet argument in this API
Centralize named-object creation in one factory so the worksheet/scope rule is enforced once

When it happens

Trigger: new NamedRange('Total') with no worksheet or scope; passing a null sheet obtained from $spreadsheet->getSheetByName('Q1') when the sheet title does not match (whitespace, escaping, or case issues); building many ranges in a loop where the sheet variable is occasionally null.

Common situations: Assuming a workbook-global name needs no worksheet; sheet lookups returning null because the sheet was renamed or the title contains quotes/apostrophes that were not matched exactly.

Related errors

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