PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Column $column is out of range ({$this->startColumnIndex} -

Error message

Column $column is out of range ({$this->startColumnIndex} - {$this->endColumnIndex})

What it means

ColumnIterator walks the columns of a worksheet between a start and end column (defaults 'A' to the sheet's highest column, narrowable via the constructor or resetStart/resetEnd). seek() repositions the pointer to a given column address and throws when that column's numeric index (A=1, B=2, ...) is outside the iterator's bounds. The message prints numeric indexes, so 'Column 7 is out of range (1 - 5)' means column G was requested on an iterator that ends at column E.

Source

Thrown at src/PhpSpreadsheet/Worksheet/ColumnIterator.php:109

    {
        $endColumn = $endColumn ?: $this->worksheet->getHighestColumn();
        $this->endColumnIndex = Coordinate::columnIndexFromString($endColumn);

        return $this;
    }

    /**
     * Set the column pointer to the selected column.
     *
     * @param string $column The column address to set the current pointer at
     *
     * @return $this
     */
    public function seek(string $column = 'A'): static
    {
        $column = Coordinate::columnIndexFromString($column);
        if (($column < $this->startColumnIndex) || ($column > $this->endColumnIndex)) {
            throw new PhpSpreadsheetException(
                "Column $column is out of range ({$this->startColumnIndex} - {$this->endColumnIndex})"
            );
        }
        $this->currentColumnIndex = $column;

        return $this;
    }

    /**
     * Rewind the iterator to the starting column.
     */
    public function rewind(): void
    {
        $this->currentColumnIndex = $this->startColumnIndex;
    }

    /**
     * Return the current column in this worksheet.

View on GitHub (pinned to 65b080eef4)

Solutions

1. Seek only columns within the range, or widen the range when constructing the iterator: new ColumnIterator($sheet, 'B', 'H') or $iterator->resetEnd('H').
2. Compare Coordinate::columnIndexFromString($column) against the same start/end values you gave the iterator before calling seek().
3. If the target may legitimately be absent, wrap seek() in a try/catch for PhpSpreadsheetException and fall back to rewind() or skip.

Example fix

// before
$iterator = new ColumnIterator($sheet, 'B', 'F');
$iterator->seek('H'); // Column 8 is out of range (2 - 6)

// after
$idx = Coordinate::columnIndexFromString('H');
if ($idx >= 2 && $idx <= 6) {
    $iterator->seek('H');
}

$start = Coordinate::columnIndexFromString('B');
$end = Coordinate::columnIndexFromString('F');
$idx = Coordinate::columnIndexFromString($wantedColumn);
if ($idx < $start) {
    $wantedColumn = 'B';
} elseif ($idx > $end) {
    $wantedColumn = 'F'; // clamp to the iterator's end column
}
(new ColumnIterator($sheet, 'B', 'F'))->seek($wantedColumn);

function columnWithinRange(string $column, string $start, string $end): bool
{
    $i = Coordinate::columnIndexFromString($column);
    return $i >= Coordinate::columnIndexFromString($start)
        && $i <= Coordinate::columnIndexFromString($end);
}

try {
    $iterator->seek($column);
} catch (PhpSpreadsheetException $e) {
    // column outside iterator range: widen the range or skip gracefully
    $iterator->rewind();
}

When it happens

Trigger: (new ColumnIterator($sheet, 'B', 'F'))->seek('G') — beyond the narrowed end column; seek('A') when the iterator starts at 'C'; seeking a column found by a header lookup on the full sheet while iterating only a sub-range.

Common situations: Iterating a column subset (e.g. B:F) but reusing a coordinate computed for the whole sheet; off-by-one column math combined with Coordinate::stringFromColumnIndex; running seek() on an iterator built for a previous, wider dataset (e.g. after loading a smaller file).

Related errors

• Start column ({$startColumn}) is beyond highest column ({$th
• Column is outside of current table range.
• Unsupported binary comparison operator
• Cloning the calculation engine is not allowed!
• Unsupported numeric binary operation

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