PHPOffice/PhpSpreadsheet · error · PhpOffice\PhpSpreadsheet\Exception

Column references should not be numeric.

Error message

Column references should not be numeric.

What it means

insertNewColumnBefore(string $before, int $numberOfColumns = 1) expects a column letter string such as 'B' or 'AC'. The is_numeric() check deliberately rejects numeric strings like '3', because they would otherwise be treated as an unintended (and valid-looking) column name; the numeric counterpart is insertNewColumnBeforeByIndex().

Source

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

        return $this;
    }

    /**
     * Insert a new column, updating all possible related data.
     *
     * @param string $before Insert before this column Name, eg: 'A'
     * @param int $numberOfColumns Number of new columns to insert
     *
     * @return $this
     */
    public function insertNewColumnBefore(string $before, int $numberOfColumns = 1): static
    {
        if (!is_numeric($before)) {
            $objReferenceHelper = ReferenceHelper::getInstance();
            $objReferenceHelper->insertNewBefore($before . '1', $numberOfColumns, 0, $this);
        } else {
            throw new Exception('Column references should not be numeric.');
        }

        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);
        }

View on GitHub (pinned to 65b080eef4)

Solutions

1. Use the numeric API: $sheet->insertNewColumnBeforeByIndex($index, $count).
2. Or convert first: Coordinate::stringFromColumnIndex($index) maps 1 to 'A'.
3. Standardize on one representation (letters or indexes) per code path and convert only at the API boundary.

Example fix

// before
$colIndex = 4;
$sheet->insertNewColumnBefore((string) $colIndex); // throws: numeric

// after
$sheet->insertNewColumnBeforeByIndex($colIndex);
// or
$sheet->insertNewColumnBefore(Coordinate::stringFromColumnIndex($colIndex)); // 'D'

use PhpOffice\PhpSpreadsheet\Cell\Coordinate;

$column = is_int($columnInput)
    ? Coordinate::stringFromColumnIndex($columnInput)
    : $columnInput;
$sheet->insertNewColumnBefore($column, 2);

/** Column letters only: 'A'..'Z', 'AA'..; no digits, no '$'. */
function isColumnLetter(string $column): bool
{
    return $column !== '' && ctype_alpha($column);
}

When it happens

Trigger: insertNewColumnBefore('2'); insertNewColumnBefore((string) $columnNumber) after computing a numeric index with Coordinate::columnIndexFromString() or a loop counter and forgetting to convert it back to letters.

Common situations: Mixed bookkeeping where columns are tracked as integers for range math but passed to the string-based API; (string) casts of ints to satisfy the string type; user-supplied 'column number' input forwarded unchanged.

Related errors

• Columns can only be inserted before at least 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.
• Columns to be deleted should at least start from column A (1

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