qax-os/excelize · error

row number exceeds maximum limit

Error message

row number exceeds maximum limit

What it means

ErrMaxRows is returned when an operation would produce a row number beyond the maximum supported row limit (1,048,576 rows for xlsx). It guards row-dimension adjustments and formula row-number adjustments from overflowing the format's limits.

Source

Thrown at errors.go:102

	// value exceeds limit.
	ErrFormControlValue = fmt.Errorf("scroll value must be an integer from 0 to %d", MaxFormControlValue)
	// ErrGroupSheets defined the error message on group sheets.
	ErrGroupSheets = errors.New("group worksheet must contain an active worksheet")
	// ErrImgExt defined the error message on receive an unsupported image
	// extension.
	ErrImgExt = errors.New("unsupported image extension")
	// ErrInvalidFormula defined the error message on receive an invalid
	// formula.
	ErrInvalidFormula = errors.New("formula not valid")
	// ErrMaxFilePathLength defined the error message on receive the file path
	// length overflow.
	ErrMaxFilePathLength = fmt.Errorf("file path length exceeds maximum limit %d characters", MaxFilePathLength)
	// ErrMaxRowHeight defined the error message on receive an invalid row
	// height.
	ErrMaxRowHeight = fmt.Errorf("the height of the row must be less than or equal to %d points", MaxRowHeight)
	// ErrMaxRows defined the error message on receive a row number exceeds
	// maximum limit.
	ErrMaxRows = errors.New("row number exceeds maximum limit")
	// ErrNameLength defined the error message on receiving the defined name or
	// table name length exceeds the limit.
	ErrNameLength = fmt.Errorf("the name length exceeds the %d characters limit", MaxFieldLength)
	// ErrMaxGraphicAltTextLength defined the error message on receiving the
	// graphic alt text length exceeds the limit.
	ErrMaxGraphicAltTextLength = fmt.Errorf("the alt text length exceeds the %d characters limit", MaxGraphicAltTextLength)
	// ErrMaxGraphicNameLength defined the error message on receiving the
	// graphic name length exceeds the limit.
	ErrMaxGraphicNameLength = fmt.Errorf("the name length exceeds the %d characters limit", MaxGraphicNameLength)
	// ErrOptionsUnzipSizeLimit defined the error message for receiving
	// invalid UnzipSizeLimit and UnzipXMLSizeLimit.
	ErrOptionsUnzipSizeLimit = errors.New("the value of UnzipSizeLimit should be greater than or equal to UnzipXMLSizeLimit")
	// ErrOutlineLevel defined the error message on receive an invalid outline
	// level number.
	ErrOutlineLevel = errors.New("invalid outline level")
	// ErrPageSetupAdjustTo defined the error message for receiving a page setup
	// adjust to value exceeds limit.
	ErrPageSetupAdjustTo = errors.New("adjust to value must be an integer from 0 to 400")

View on GitHub (pinned to f2483381fb)

Solutions

1. Reduce the insert/offset amount so the resulting last row stays at or below 1,048,576.
2. Check the last row plus offset against the TotalRows limit before performing the adjustment.
3. Split data across multiple sheets when the row count approaches the maximum.
4. For formula adjustments, clamp or rewrite references so shifted row numbers stay within range.

Example fix

// before
offset := 1000 // last row is 1048570, would exceed limit
// after
if lastRow+offset > 1048576 { offset = 1048576 - lastRow }

const maxRows = 1048576
if lastRow+offset > maxRows {
    return fmt.Errorf("operation would exceed max row limit: %d > %d", lastRow+offset, maxRows)
}

if err := adjustRows(f, sheet, row, offset); errors.Is(err, excelize.ErrMaxRows) {
    // reduce the offset to fit or split across sheets
    offset = maxRows - lastRow
    err = adjustRows(f, sheet, row, offset)
}

When it happens

Trigger: Calling adjust APIs (e.g. duplicate/insert row operations in adjustRowDimensions) with an offset that pushes the last row past TotalRows, or a formula like "=A1048576" being shifted down by adjustFormulaRowNumber.

Common situations: Programmatically inserting or duplicating many rows near the bottom of a full sheet, auto-filling formulas that reference the last valid row, or generated reports exceeding the xlsx row cap.

Related errors

• fill type value must be one of 'gradient' or 'pattern'
• fill color value must be an array of two colors for 'gradien
• fill shading value must be between 0 and 16 for 'gradient' t
• fill color value must be empty or an array of one color for
• fill pattern value must be between 0 and 18

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