PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Named range {$definedName} is not accessible from within she

Error message

Named range {$definedName} is not accessible from within sheet {$this->getTitle()}

What it means

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.

Source

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

            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(
                    'Named range ' . $definedName . ' is not accessible from within sheet ' . $this->getTitle()
                );
            }
        }

        return $namedRange;
    }

    /**
     * Create array from a range of cells.
     *
     * @param string $definedName The Named Range that should be returned
     * @param null|bool|float|int|RichText|string $nullValue Value returned in the array entry if a cell doesn't exist
     * @param bool $calculateFormulas Should formulas be calculated?
     * @param bool $formatData Should formatting be applied to cell values?
     * @param bool $returnCellRef False - Return a simple array of rows and columns indexed by number counting from zero
     *                             True - Return rows and columns indexed by their actual row and column IDs
     * @param bool $ignoreHidden False - Return values for rows/columns even if they are defined as hidden.

View on GitHub (pinned to 65b080eef4)

Solutions

1. Call namedRangeToArray() on the owning sheet: $owner = $named->getWorksheet().
2. Re-define the name as workbook-global (localOnly false, no sheet scope) when multiple sheets need it.
3. Or register a duplicate definition scoped to the consuming sheet.

Example fix

use PhpOffice\PhpSpreadsheet\DefinedName;

// before
$data = $sheet2->namedRangeToArray('LocalBlock'); // defined localOnly on Sheet1

// after
$named = DefinedName::resolveName('LocalBlock', $sheet1);
$owner = ($named !== null && $named->getLocalOnly()) ? ($named->getWorksheet() ?? $sheet1) : $sheet2;
$data = $owner->namedRangeToArray('LocalBlock');

use PhpOffice\PhpSpreadsheet\DefinedName;

$named = DefinedName::resolveName($name, $sheet);
$accessible = $named !== null
    && !$named->isFormula()
    && (!$named->getLocalOnly() || $named->getWorksheet() === $sheet);
if ($accessible) {
    $data = $sheet->namedRangeToArray($name);
}

use PhpOffice\PhpSpreadsheet\Exception as SpreadsheetException;

try {
    $data = $sheet->namedRangeToArray($name);
} catch (SpreadsheetException $e) {
    if (str_contains($e->getMessage(), 'not accessible')) {
        $owner = DefinedName::resolveName($name, $sheet)?->getWorksheet();
        $data = $owner?->namedRangeToArray($name) ?? [];
    } else {
        throw $e;
    }
}

When it happens

Trigger: $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.

Common situations: 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.

Related errors

• Sheet not found for named range: {$namedRange->getName()}
• Named Range {$definedName} does not exist.
• Defined Named {$definedName} is a formula, not a range or ce
• Cannot update when cell is not bound to a worksheet
• Cannot get column when cell is not bound to a worksheet

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