qax-os/excelize · error

the alt text length exceeds the %d characters limit

Error message

the alt text length exceeds the %d characters limit

What it means

ErrMaxGraphicAltTextLength is returned by parseGraphicOptions when the GraphicOptions/PictureOptions AltText exceeds MaxGraphicAltTextLength characters (UTF-16 count). Alt text is stored in the drawing XML as accessible description and Excel enforces a length limit, so excelize validates before writing.

Source

Thrown at errors.go:108

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

View on GitHub (pinned to f2483381fb)

Solutions

1. Truncate AltText to MaxGraphicAltTextLength before calling AddPicture
2. Sanitize/shorten captions at the source (CMS or template) rather than at the call site
3. Validate with a UTF-16-aware length check and surface a friendly message to the user

Example fix

// before
opts := &excelize.GraphicOptions{AltText: longCaption}
err := f.AddPicture("Sheet1", "Q25", "img.png", opts)
// after
if len([]rune(longCaption)) > excelize.MaxGraphicAltTextLength {
	longCaption = longCaption[:excelize.MaxGraphicAltTextLength]
}
err := f.AddPicture("Sheet1", "Q25", "img.png", &excelize.GraphicOptions{AltText: longCaption})

if len([]rune(altText)) > excelize.MaxGraphicAltTextLength { altText = altText[:excelize.MaxGraphicAltTextLength] }

When it happens

Trigger: f.AddPicture("Sheet1", "Q25", "img.svg", &excelize.GraphicOptions{AltText: <string longer than MaxGraphicAltTextLength>}) or any API that routes options through parseGraphicOptions.

Common situations: Auto-filling alt text from long image captions, product descriptions, or URL strings; bulk-importing accessibility metadata from a CMS without truncation.

Related errors

• the sheet name length exceeds the %d characters limit
• data validation range exceeds limit
• the same name already exists on the scope
• no defined name on the scope
• the same name sheet already exists

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