qax-os/excelize · error

cannot convert cell %q to coordinates: %v

Error message

cannot convert cell %q to coordinates: %v

What it means

newCellNameToCoordinatesError wraps a lower-level failure that occurred while converting an alphanumeric cell reference (like "A1") into [col, row] coordinates. It is used across adjustment/remerge code paths (merge cells, auto filter, calc chain, formula adjust) so callers get context about which cell could not be parsed and the underlying reason.

Source

Thrown at errors.go:231

type ErrSheetNotExist struct {
	SheetName string
}

// Error returns the error message on receiving the non existing sheet name.
func (err ErrSheetNotExist) Error() string {
	return fmt.Sprintf("sheet %s does not exist", err.SheetName)
}

// newAddCommentError defined the error message on the comment already exist in
// the cell.
func newAddCommentError(cell string) error {
	return fmt.Errorf("comment already exist on cell %s", cell)
}

// newCellNameToCoordinatesError defined the error message on converts
// alphanumeric cell name to coordinates.
func newCellNameToCoordinatesError(cell string, err error) error {
	return fmt.Errorf("cannot convert cell %q to coordinates: %v", cell, err)
}

// newChartTitleError defined the error message on receiving the invalid chart
// title parameters.
func newChartTitleError(name string) error {
	return fmt.Errorf("chart title field %s value must be an integer from 0 to 100", name)
}

// newCoordinatesToCellNameError defined the error message on converts [X, Y]
// coordinates to alpha-numeric cell name.
func newCoordinatesToCellNameError(col, row int) error {
	return fmt.Errorf("invalid cell reference [%d, %d]", col, row)
}

// newFieldLengthError defined the error message on receiving the field length
// overflow.
func newFieldLengthError(name string) error {
	return fmt.Errorf("field %s must be less than or equal to 255 characters", name)

View on GitHub (pinned to f2483381fb)

Solutions

1. Validate cell references before use, e.g. with excelize.CoordinatesToCellName/CellNameToCoordinates round-trip in a defer-and-check
2. Fix the source of the malformed reference (empty string, swapped row/column)
3. Inspect the wrapped %v cause in the message to see the exact parse failure

Example fix

// before
f.SetCellFormula("Sheet1", userRef, "=SUM(A1:A2)") // userRef may be invalid
// after
if _, _, err := excelize.CellNameToCoordinates(userRef); err != nil {
	return fmt.Errorf("invalid cell ref %q", userRef)
}
f.SetCellFormula("Sheet1", userRef, "=SUM(A1:A2)")

if _, _, err := excelize.CellNameToCoordinates(ref); err != nil { return fmt.Errorf("bad cell ref %q", ref) }

func validCellRef(s string) bool { _, _, err := excelize.CellNameToCoordinates(s); return err == nil }

When it happens

Trigger: Passing a malformed cell reference (e.g. "", "1A", "AAA0000" beyond limits, or a name that fails coordinate conversion) into APIs that touch merged cells, filters, formulas, or the calc chain during sheet adjust operations.

Common situations: Building cell references by string concatenation and producing empty or off-by-one values; user-supplied ranges with typos; column letters exceeding Excel's range (e.g. "XFE1").

Related errors

• invalid cell reference [%d, %d]
• formula not valid
• coordinates length must be 4
• data validation range exceeds limit
• the same name already exists on the scope

AI-assisted analysis of qax-os/excelize@f2483381fb (2026-09-02). Data as JSON: /api/errors/56d1e7e04250e0c4. Report an issue: GitHub.