{"record":{"id":"82925da9ff49d8e5","repo":"PHPOffice/PhpSpreadsheet","slug":"named-range-definedname-is-not-accessible-from","errorCode":null,"errorMessage":"Named range {$definedName} is not accessible from within sheet {$this->getTitle()}","messagePattern":"Named range (.+?) is not accessible from within sheet (.+?)","errorType":"exception","errorClass":"PhpOffice\\PhpSpreadsheet\\Exception","httpStatus":null,"severity":"error","filePath":"src/PhpSpreadsheet/Worksheet/Worksheet.php","lineNumber":3460,"sourceCode":"            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(\n                    'Named range ' . $definedName . ' is not accessible from within sheet ' . $this->getTitle()\n                );\n            }\n        }\n\n        return $namedRange;\n    }\n\n    /**\n     * Create array from a range of cells.\n     *\n     * @param string $definedName The Named Range that should be returned\n     * @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist\n     * @param bool $calculateFormulas Should formulas be calculated?\n     * @param bool $formatData Should formatting be applied to cell values?\n     * @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero\n     *                             True - Return rows and columns indexed by their actual row and column IDs\n     * @param bool $ignoreHidden False - Return values for rows/columns even if they are defined as hidden.","sourceCodeStart":3442,"sourceCodeEnd":3478,"githubUrl":"https://github.com/PHPOffice/PhpSpreadsheet/blob/65b080eef4d9fd11a5796135ab145883e5c3d6a6/src/PhpSpreadsheet/Worksheet/Worksheet.php#L3442-L3478","documentation":"Defined names can be scoped locally to one worksheet (localOnly). namedRangeToArray() resolves the name first and then verifies scope: if the name is local-only and its owning worksheet is null or is not the sheet the call was made on (an identity === check), it throws 'Named range ... is not accessible from within sheet ...'. Workbook-global names never trigger this.","triggerScenarios":"$sheet2->namedRangeToArray('LocalBlock') where LocalBlock was added with setLocalOnly(true) scoped to Sheet1; sheets removed and re-created so the name's stored worksheet no longer matches the current object.","commonSituations":"Imported Excel files where Name Manager shows 'Scope: Sheet1'; code assuming all names are global and calling from any sheet; workflows that clone or rebuild worksheets after names were defined.","solutions":["Call namedRangeToArray() on the owning sheet: $owner = $named->getWorksheet().","Re-define the name as workbook-global (localOnly false, no sheet scope) when multiple sheets need it.","Or register a duplicate definition scoped to the consuming sheet."],"exampleFix":"use PhpOffice\\PhpSpreadsheet\\DefinedName;\n\n// before\n$data = $sheet2->namedRangeToArray('LocalBlock'); // defined localOnly on Sheet1\n\n// after\n$named = DefinedName::resolveName('LocalBlock', $sheet1);\n$owner = ($named !== null && $named->getLocalOnly()) ? ($named->getWorksheet() ?? $sheet1) : $sheet2;\n$data = $owner->namedRangeToArray('LocalBlock');","handlingStrategy":"validation","validationCode":"use PhpOffice\\PhpSpreadsheet\\DefinedName;\n\n$named = DefinedName::resolveName($name, $sheet);\n$accessible = $named !== null\n    && !$named->isFormula()\n    && (!$named->getLocalOnly() || $named->getWorksheet() === $sheet);\nif ($accessible) {\n    $data = $sheet->namedRangeToArray($name);\n}","typeGuard":null,"tryCatchPattern":"use PhpOffice\\PhpSpreadsheet\\Exception as SpreadsheetException;\n\ntry {\n    $data = $sheet->namedRangeToArray($name);\n} catch (SpreadsheetException $e) {\n    if (str_contains($e->getMessage(), 'not accessible')) {\n        $owner = DefinedName::resolveName($name, $sheet)?->getWorksheet();\n        $data = $owner?->namedRangeToArray($name) ?? [];\n    } else {\n        throw $e;\n    }\n}","preventionTips":["Prefer workbook-global names when several sheets must consume them.","Treat names in uploaded files as sheet-scoped until proven global (check getLocalOnly()).","Resolve the owning worksheet via DefinedName::resolveName()->getWorksheet() before calling."],"tags":["phpspreadsheet","worksheet","named-range","scope","defined-name"],"backgroundTag":"named-range-scope","analyzedSha":"65b080eef4d9fd11a5796135ab145883e5c3d6a6","analyzedAt":"2026-08-17T05:40:41.646Z","schemaVersion":2},"datasetVersion":"2026-08-17T09:17:11.063Z"}