PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Named Range {$definedName} does not exist.

Error message

Named Range {$definedName} does not exist.

What it means

Worksheet::namedRangeToArray($definedName) resolves the name through DefinedName::resolveName() against the workbook and this worksheet before extracting values. If nothing matches, it throws 'Named Range ... does not exist.' The generic toArray()/rangeToArray() path uses the same resolver but with returnNullIfInvalid, so this exception is specific to the namedRangeToArray() entry point.

Source

Thrown at src/PhpSpreadsheet/Worksheet/Worksheet.php:3442

                $hiddenColumns[$col] = true;
            } else {
                $columnRef = $returnCellRef ? $col : ++$c;
                $nullRow[$columnRef] = $nullValue;
            }
        }

        return $nullRow;
    }

    private function validateNamedRange(string $definedName, bool $returnNullIfInvalid = false): ?DefinedName
    {
        $namedRange = DefinedName::resolveName($definedName, $this);
        if ($namedRange === null) {
            if ($returnNullIfInvalid) {
                return null;
            }

            throw new Exception('Named Range ' . $definedName . ' does not exist.');
        }

        if ($namedRange->isFormula()) {
            if ($returnNullIfInvalid) {
                return null;
            }

            throw new Exception('Defined Named ' . $definedName . ' is a formula, not a range or cell.');
        }

        if ($namedRange->getLocalOnly()) {
            $worksheet = $namedRange->getWorksheet();
            if ($worksheet === null || $this !== $worksheet) {
                if ($returnNullIfInvalid) {
                    return null;
                }

                throw new Exception(

View on GitHub (pinned to 65b080eef4)

Solutions

1. Check existence first: $spreadsheet->getNamedRange('DataRange', $sheet) returns null when it is missing.
2. List what actually exists: $spreadsheet->getNamedRanges() shows every defined name in the file.
3. Define it if it should exist: $spreadsheet->addNamedRange(new NamedRange('DataRange', $sheet, '=$A$1:$C$5')).
4. For user-supplied names, wrap the call in try/catch and degrade gracefully.

Example fix

// before
$data = $sheet->namedRangeToArray('DataRange'); // throws if undefined

// after
if ($spreadsheet->getNamedRange('DataRange', $sheet) === null) {
    throw new RuntimeException('Template missing named range DataRange');
}
$data = $sheet->namedRangeToArray('DataRange');

$name = 'DataRange';
if ($spreadsheet->getNamedRange($name, $sheet) === null) {
    throw new RuntimeException('Workbook has no named range ' . $name);
}
$data = $sheet->namedRangeToArray($name);

use PhpOffice\PhpSpreadsheet\Exception as SpreadsheetException;

try {
    $data = $sheet->namedRangeToArray($userSuppliedName);
} catch (SpreadsheetException $e) {
    if (str_contains($e->getMessage(), 'does not exist')) {
        // unknown name in the uploaded file: skip or use a default range
    } else {
        throw $e;
    }
}

When it happens

Trigger: $sheet->namedRangeToArray('MyRange') when the spreadsheet defines no such name; a typo or wrong spelling ('datarange' vs 'DataRange'); calling before $spreadsheet->addNamedRange() has registered the name; templates renamed or regenerated without the name the code expects.

Common situations: Reading user-uploaded workbooks whose defined names differ from the expected template; code updated for a new template version while users still upload the old one; names that exist in a different file than the one loaded.

Related errors

• Sheet not found for named range: {$namedRange->getName()}
• Defined Named {$definedName} is a formula, not a range or ce
• Named range {$definedName} is not accessible from within she
• Freeze pane can not be set on a range of cells.
• Rows can only be inserted before at least row 1.

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