the sheet name length exceeds the %d characters limit

Error message

the sheet name length exceeds the %d characters limit

What it means

ErrSheetNameLength is returned by checkSheetName when a worksheet name exceeds MaxSheetNameLength (31) characters, matching Excel's hard limit on sheet titles. NewSheet and SetSheetName run the name through this validation and fail fast instead of producing a workbook Excel would refuse to open.

Source

Thrown at errors.go:152

	// this kind of "show values as" type and base field requires a base item.
	ErrPivotTableShowValuesAsBaseItem = errors.New("this kind of show values as type and base field requires a base item")
	// ErrPivotTableClassicLayout defined the error message on enable
	// ClassicLayout and CompactData in the same time.
	ErrPivotTableClassicLayout = errors.New("cannot enable ClassicLayout and CompactData in the same time")
	// ErrSave defined the error message for saving file.
	ErrSave = errors.New("no path defined for file, consider File.WriteTo or File.Write")
	// ErrSheetIdx defined the error message on receive the invalid worksheet
	// index.
	ErrSheetIdx = errors.New("invalid worksheet index")
	// ErrSheetNameBlank defined the error message on receive the blank sheet
	// name.
	ErrSheetNameBlank = errors.New("the sheet name can not be blank")
	// ErrSheetNameInvalid defined the error message on receive the sheet name
	// contains invalid characters.
	ErrSheetNameInvalid = errors.New("the sheet can not contain any of the characters :\\/?*[or]")
	// ErrSheetNameLength defined the error message on receiving the sheet
	// name length exceeds the limit.
	ErrSheetNameLength = fmt.Errorf("the sheet name length exceeds the %d characters limit", MaxSheetNameLength)
	// ErrSheetNameSingleQuote defined the error message on the first or last
	// character of the sheet name was a single quote.
	ErrSheetNameSingleQuote = errors.New("the first or last character of the sheet name can not be a single quote")
	// ErrSparkline defined the error message on receive the invalid sparkline
	// parameters.
	ErrSparkline = errors.New("must have the same number of 'Location' and 'Range' parameters")
	// ErrSparklineLocation defined the error message on missing Location
	// parameters
	ErrSparklineLocation = errors.New("parameter 'Location' is required")
	// ErrSparklineRange defined the error message on missing sparkline Range
	// parameters
	ErrSparklineRange = errors.New("parameter 'Range' is required")
	// ErrSparklineStyle defined the error message on receive the invalid
	// sparkline Style parameters.
	ErrSparklineStyle = errors.New("parameter 'Style' value must be an integer from 0 to 35")
	// ErrSparklineType defined the error message on receive the invalid
	// sparkline Type parameters.
	ErrSparklineType = errors.New("parameter 'Type' value must be one of 'line', 'column' or 'win_loss'")

View on GitHub (pinned to f2483381fb)

Solutions

Truncate the sheet name to 31 characters before calling NewSheet/SetSheetName
Also sanitize invalid characters (: \/ ? * [ ]) in the same helper since those raise ErrSheetNameInvalid
Keep a short name plus put the long title in cell A1 of the sheet instead

Example fix

// before
name := longReportTitle // e.g. 60 chars
_, err := f.NewSheet(name)
// after
if len([]rune(name)) > 31 {
	name = name[:31]
}
_, err := f.NewSheet(name)

Defensive patterns

Strategy: validation

Validate before calling

func safeSheetName(s string) string {
	if len([]rune(s)) > 31 { s = s[:31] }
	return strings.Trim(s, "'")
}

Type guard

func okSheetName(s string) bool { return len([]rune(s)) <= 31 && !strings.ContainsAny(s, ":\\/?*[]'") }

Prevention

Always route sheet names through a 31-char truncation helper
Also strip illegal characters : \/ ? * [ ] and leading/trailing quotes
Put long descriptive titles in cell A1 instead of the sheet name

When it happens

Trigger: f.NewSheet(strings.Repeat("x", 32)) or f.SetSheetName(old, newName) where the new name is longer than 31 characters (the test uses ':\\/?*[]Maximum 31 characters allowed in sheet title.').

Common situations: Deriving sheet names from report titles, file names, or user-entered project names without truncation; date+label concatenations that push past 31 chars.

Related errors

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