PHPOffice/PhpSpreadsheet · error · SpreadsheetException

Cannot update when cell is not bound to a worksheet

Error message

Cannot update when cell is not bound to a worksheet

What it means

Cell::updateInCollection() writes the cell back into its parent Cells collection. The collection pointer ($this->parent) is nulled by detach() (used when cells are evicted from the collection cache or explicitly detached), so calling updateInCollection() on such a cell throws PhpOffice\PhpSpreadsheet\Exception 'Cannot update when cell is not bound to a worksheet'. Normal setValue() flows call it internally after attach, so hitting it directly means you are mutating a detached cell object.

Source

Thrown at src/PhpSpreadsheet/Cell/Cell.php:80

    /**
     * Attributes of the formula.
     *
     * @var null|array<string, string>
     */
    private ?array $formulaAttributes = null;

    private IgnoredErrors $ignoredErrors;

    /**
     * Update the cell into the cell collection.
     *
     * @throws SpreadsheetException
     */
    public function updateInCollection(): self
    {
        $parent = $this->parent;
        if ($parent === null) {
            throw new SpreadsheetException('Cannot update when cell is not bound to a worksheet');
        }
        $parent->update($this);

        return $this;
    }

    public function detach(): void
    {
        $this->parent = null;
    }

    public function attach(Cells $parent): void
    {
        $this->parent = $parent;
    }

    /**
     * Create a new Cell.

View on GitHub (pinned to 65b080eef4)

Solutions

1. Re-fetch the cell through the worksheet right before mutating: $sheet->getCell('A1')->setValue($v) instead of caching Cell objects
2. Drop stale references after detach/clone/garbage-collect cycles and always go through getCell()
3. After removing/recreating a worksheet, obtain fresh Cell objects from the new sheet
4. If you must call it, guard with a try/catch PhpOffice\PhpSpreadsheet\Exception and re-attach via $sheet->getCellCollection()->add or re-fetch

Example fix

// before: stale cached object
$cell = $sheet->getCell('A1');
// ... later, after the cell was detached
$cell->updateInCollection(); // throws

// after: fetch at point of use
$sheet->getCell('A1')->setValue($newValue);

// Prefer not to hold Cell objects at all; if you must, verify liveness cheaply:
try {
    $cell->getCoordinate(); // throws when detached
    $alive = true;
} catch (\PhpOffice\PhpSpreadsheet\Exception) {
    $alive = false;
}

function isCellBound(\PhpOffice\PhpSpreadsheet\Cell\Cell $cell): bool
{
    try {
        $cell->getCoordinate();
        return true;
    } catch (\PhpOffice\PhpSpreadsheet\Exception) {
        return false;
    }
}

try {
    $cell->updateInCollection();
} catch (\PhpOffice\PhpSpreadsheet\Exception $e) {
    if (str_contains($e->getMessage(), 'not bound to a worksheet')) {
        $sheet->getCell($coord)->setValue($cell->getValue()); // re-fetch and re-apply
    } else { throw $e; }
}

When it happens

Trigger: $cell->detach(); $cell->updateInCollection(); holding a Cell object across operations that garbage-collect/evict the collection (large sheets with cell caching) and then calling setValue/updateInCollection on the stale object; re-using a Cell instance after its worksheet was unset/removed from the spreadsheet.

Common situations: Long-lived references to Cell objects in user code while the worksheet gets rewritten or cells get cloned/detached; wrappers that cache Cell objects for performance; deleting a sheet but keeping cell references from it; memory-pressure eviction with big workloads.

Related errors

• Cannot get column when cell is not bound to a worksheet
• Worksheet no longer exists
• Cannot get row when cell is not bound to a worksheet
• Cannot check for data validation when cell is not bound to a
• Cannot get data validation for cell that is not bound to a w

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