qax-os/excelize · error

the value of UnzipSizeLimit should be greater than or equal

Error message

the value of UnzipSizeLimit should be greater than or equal to UnzipXMLSizeLimit

What it means

ErrOptionsUnzipSizeLimit is returned by option validation when opening a workbook if Options.UnzipXMLSizeLimit exceeds Options.UnzipSizeLimit. The per-file uncompressed XML size limit logically cannot be larger than the overall uncompressed size limit.

Source

Thrown at errors.go:114

	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")
	// ErrParameterInvalid defined the error message on receive the invalid
	// parameter.
	ErrParameterInvalid = errors.New("parameter is invalid")
	// ErrParameterRequired defined the error message on receive the empty
	// parameter.
	ErrParameterRequired = errors.New("parameter is required")
	// ErrPasswordLengthInvalid defined the error message on invalid password
	// length.
	ErrPasswordLengthInvalid = errors.New("password length invalid")
	// ErrPivotTableShowValuesAsBaseField defined the error message on enable
	// this kind of "show values as" type requires a base field.
	ErrPivotTableShowValuesAsBaseField = errors.New("this kind of show values as type requires a base field")

View on GitHub (pinned to f2483381fb)

Solutions

1. Set UnzipXMLSizeLimit to a value less than or equal to UnzipSizeLimit (default XML limit is 16MB, total 2GB).
2. If you need a larger per-XML limit, raise UnzipSizeLimit accordingly (UnzipSizeLimit >= UnzipXMLSizeLimit).
3. Validate the relationship between the two options in your config-loading code before opening files.

Example fix

// before
opts := Options{UnzipSizeLimit: 1, UnzipXMLSizeLimit: 2}
// after
opts := Options{UnzipSizeLimit: 2048, UnzipXMLSizeLimit: 1024}

if opts.UnzipXMLSizeLimit > opts.UnzipSizeLimit {
    return errors.New("UnzipXMLSizeLimit must be <= UnzipSizeLimit")
}

func optionsValid(o excelize.Options) bool {
    return o.UnzipXMLSizeLimit <= o.UnzipSizeLimit
}

f, err := excelize.OpenReader(r, opts)
if errors.Is(err, excelize.ErrOptionsUnzipSizeLimit) {
    opts.UnzipSizeLimit = opts.UnzipXMLSizeLimit
    f, err = excelize.OpenReader(r, opts)
}

When it happens

Trigger: OpenReader/OpenFile with Options{UnzipSizeLimit: 1, UnzipXMLSizeLimit: 2}, or any configuration where UnzipXMLSizeLimit > UnzipSizeLimit; the check runs in checkOpenReaderOptions.

Common situations: Tuning size limits independently and setting the XML limit higher than the total limit, misreading which limit is the total versus per-file cap, or copying example configs with inconsistent values.

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/1fe567296a8b5840. Report an issue: GitHub.