PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Columns can only be inserted before at least column A (1).

Error message

Columns can only be inserted before at least column A (1).

What it means

insertNewColumnBeforeByIndex(int $beforeColumnIndex, int $numberOfColumns = 1) converts a 1-based column index to its letter and delegates to insertNewColumnBefore(). Column A is index 1, so an index of 0 or negative is rejected before the conversion runs.

Source

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

        return $this;
    }

    /**
     * Insert a new column, updating all possible related data.
     *
     * @param int $beforeColumnIndex Insert before this column ID (numeric column coordinate of the cell)
     * @param int $numberOfColumns Number of new columns to insert
     *
     * @return $this
     */
    public function insertNewColumnBeforeByIndex(int $beforeColumnIndex, int $numberOfColumns = 1): static
    {
        if ($beforeColumnIndex >= 1) {
            return $this->insertNewColumnBefore(Coordinate::stringFromColumnIndex($beforeColumnIndex), $numberOfColumns);
        }

        throw new Exception('Columns can only be inserted before at least column A (1).');
    }

    /**
     * Delete a row, updating all possible related data.
     *
     * @param int $row Remove rows, starting with this row number
     * @param int $numberOfRows Number of rows to remove
     *
     * @return $this
     */
    public function removeRow(int $row, int $numberOfRows = 1): static
    {
        if ($row < 1) {
            throw new Exception('Rows to be deleted should at least start from row 1.');
        }
        if ($numberOfRows === 0) {
            return $this;
        }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Pass >= 1 (A = 1, B = 2, Z = 26, AA = 27).
2. Convert 0-based loops: insertNewColumnBeforeByIndex($i + 1).
3. Clamp computed indexes with max(1, $index).

Example fix

// before
for ($col = 0; $col < 5; ++$col) {
    $sheet->insertNewColumnBeforeByIndex($col); // throws on first iteration
}

// after
for ($col = 1; $col <= 5; ++$col) {
    $sheet->insertNewColumnBeforeByIndex($col);
}

for ($col = 1; $col <= $maxCol; ++$col) { // column A is index 1
    $sheet->insertNewColumnBeforeByIndex($col);
}

/** Column indexes are 1-based: A = 1, B = 2, ... */
function isPositiveColumnIndex(int $index): bool
{
    return $index >= 1;
}

When it happens

Trigger: insertNewColumnBeforeByIndex(0); a 0-based column loop counter passed straight through; index arithmetic such as $col - 1 hitting 0 at the first column.

Common situations: Looping for ($col = 0; $col < $n; ++$col) over grid data; mapping 0-based array columns to spreadsheet columns without adding 1.

Related errors

• Column references should not be numeric.
• Columns to be deleted should at least start from column A (1
• Freeze pane can not be set on a range of cells.
• Rows can only be inserted before at least row 1.
• Rows to be deleted should at least start from row 1.

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