qax-os/excelize · error

the name length exceeds the

Error message

the name length exceeds the %d characters limit

What it means

ErrNameLength is returned when a user-supplied name (defined name or pivot table name) exceeds MaxFieldLength (255) characters as counted in UTF-16 code units. parseFormatPivotTableSet validates the PivotTableOptions.Name before building the pivot table, and checkDefinedName validates defined names. Excel caps these identifiers, so excelize rejects longer ones up front.

Solutions

1. Shorten the name to <= 255 UTF-16 characters before calling the API
2. Generate a shorter deterministic name (e.g. truncate + hash suffix) when names are built from user data
3. Check length first with utf8.RuneCountInString/UTF-16-aware counting to fail early in your own code

Example fix

// before
name := longDerivedName // may exceed 255
err := f.AddPivotTable(&excelize.PivotTableOptions{Name: name, ...})
// after
if len([]rune(name)) > 255 {
	name = name[:250] + "_pt"
}
err := f.AddPivotTable(&excelize.PivotTableOptions{Name: name, ...})

if len([]rune(name)) > 255 { return fmt.Errorf("name too long") }

When it happens

Trigger: f.AddPivotTable(&excelize.PivotTableOptions{Name: strings.Repeat("x", 256), ...}); defining a workbook/table name longer than 255 UTF-16 characters via the name-related APIs.

Common situations: Generating names programmatically from long strings (e.g. concatenating dataset IDs or timestamps into a pivot name); auto-derived names from file titles or query text.

Related errors

• base field does not exist in shared items
• data fields appear both in the pivot table column fields…
• data fields appear both in the pivot table row fields and…
• ErrParameterRequired
• ErrPivotTableClassicLayout

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

Appendix: source

Thrown at errors.go:105

	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")
	// ErrParameterInvalid defined the error message on receive the invalid
	// parameter.
	ErrParameterInvalid = errors.New("parameter is invalid")

View on GitHub (pinned to f2483381fb)