{"record":{"id":"343ca86a19b878a2","repo":"PHPOffice/PhpSpreadsheet","slug":"named-range-definedname-does-not-exist","errorCode":null,"errorMessage":"Named Range {$definedName} does not exist.","messagePattern":"Named Range (.+?) does not exist\\.","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Worksheet/Worksheet.php","lineNumber":3442,"sourceCode":"                $hiddenColumns[$col] = true;\n            } else {\n                $columnRef = $returnCellRef ? $col : ++$c;\n                $nullRow[$columnRef] = $nullValue;\n            }\n        }\n\n        return $nullRow;\n    }\n\n    private function validateNamedRange(string $definedName, bool $returnNullIfInvalid = false): ?DefinedName\n    {\n        $namedRange = DefinedName::resolveName($definedName, $this);\n        if ($namedRange === null) {\n            if ($returnNullIfInvalid) {\n                return null;\n            }\n\n            throw new Exception('Named Range ' . $definedName . ' does not exist.');\n        }\n\n        if ($namedRange->isFormula()) {\n            if ($returnNullIfInvalid) {\n                return null;\n            }\n\n            throw new Exception('Defined Named ' . $definedName . ' is a formula, not a range or cell.');\n        }\n\n        if ($namedRange->getLocalOnly()) {\n            $worksheet = $namedRange->getWorksheet();\n            if ($worksheet === null || $this !== $worksheet) {\n                if ($returnNullIfInvalid) {\n                    return null;\n                }\n\n                throw new Exception(","sourceCodeStart":3424,"sourceCodeEnd":3460,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Worksheet/Worksheet.php#L3424-L3460","documentation":"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.","triggerScenarios":"$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.","commonSituations":"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.","solutions":["Check existence first: $spreadsheet->getNamedRange('DataRange', $sheet) returns null when it is missing.","List what actually exists: $spreadsheet->getNamedRanges() shows every defined name in the file.","Define it if it should exist: $spreadsheet->addNamedRange(new NamedRange('DataRange', $sheet, '=$A$1:$C$5')).","For user-supplied names, wrap the call in try/catch and degrade gracefully."],"exampleFix":"// before\n$data = $sheet->namedRangeToArray('DataRange'); // throws if undefined\n\n// after\nif ($spreadsheet->getNamedRange('DataRange', $sheet) === null) {\n    throw new RuntimeException('Template missing named range DataRange');\n}\n$data = $sheet->namedRangeToArray('DataRange');","handlingStrategy":"validation","validationCode":"$name = 'DataRange';\nif ($spreadsheet->getNamedRange($name, $sheet) === null) {\n    throw new RuntimeException('Workbook has no named range ' . $name);\n}\n$data = $sheet->namedRangeToArray($name);","typeGuard":null,"tryCatchPattern":"use PhpOffice\\PhpSpreadsheet\\Exception as SpreadsheetException;\n\ntry {\n    $data = $sheet->namedRangeToArray($userSuppliedName);\n} catch (SpreadsheetException $e) {\n    if (str_contains($e->getMessage(), 'does not exist')) {\n        // unknown name in the uploaded file: skip or use a default range\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Validate template files on upload: assert every required name exists via getNamedRange().","Centralize name constants instead of repeating string literals at call sites.","When a lookup fails, dump $spreadsheet->getNamedRanges() to see the names the file actually defines."],"tags":["phpspreadsheet","worksheet","named-range","defined-name","argument-validation"],"backgroundTag":"named-range-not-found","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}