qax-os/excelize · error

unsupported image extension

Error message

unsupported image extension

What it means

ErrImgExt is returned when an image file (or byte payload name) has an extension not in the library's supported image types (e.g. bmp, gif, jpg, jpeg, png, tiff, emf, wmf). The check is performed on the file extension, case-insensitively.

Source

Thrown at errors.go:90

	// ErrFillPatternColor defined the error message on receive an invalid fill
	// color for 'pattern' type.
	ErrFillPatternColor = errors.New("fill color value must be empty or an array of one color for 'pattern' type")
	// ErrFillPattern defined the error message on receive an invalid fill
	// pattern.
	ErrFillPattern = errors.New("fill pattern value must be between 0 and 18")
	// ErrFontLength defined the error message on the length of the font
	// family name overflow.
	ErrFontLength = fmt.Errorf("the length of the font family name must be less than or equal to %d", MaxFontFamilyLength)
	// ErrFontSize defined the error message on the size of the font is invalid.
	ErrFontSize = fmt.Errorf("font size must be an integer from %d to %d points", MinFontSize, MaxFontSize)
	// ErrFormControlValue defined the error message for receiving a scroll
	// 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)

View on GitHub (pinned to f2483381fb)

Solutions

1. Convert the image to a supported format (png, jpeg, gif, bmp, tiff, emf, or wmf) before adding it.
2. Verify the file path points to an actual image, not another document type.
3. For AddPictureFromBytes, set the Ext field of the Image options to a supported extension matching the bytes.
4. Check the extension with filepath.Ext against the supported list before calling the API.

Example fix

// before
err := f.AddPicture("Sheet1", "A1", "logo.webp", opts)
// after
// convert logo.webp to logo.png first
err := f.AddPicture("Sheet1", "A1", "logo.png", opts)

var supported = map[string]bool{"bmp": true, "gif": true, "jpg": true, "jpeg": true, "png": true, "tif": true, "tiff": true, "emf": true, "wmf": true}
ext := strings.TrimPrefix(strings.ToLower(filepath.Ext(path)), ".")
if !supported[ext] {
    return fmt.Errorf("unsupported image extension: %s", ext)
}

func isSupportedImage(path string) bool {
    switch strings.ToLower(filepath.Ext(path)) {
    case ".bmp", ".gif", ".jpg", ".jpeg", ".png", ".tif", ".tiff", ".emf", ".wmf":
        return true
    }
    return false
}

err := f.AddPicture(sheet, cell, imgPath, opts)
if errors.Is(err, excelize.ErrImgExt) {
    // convert the image to PNG and retry, or report to the user
    return fmt.Errorf("image %q must be png/jpg/gif/bmp/tiff/emf/wmf: %w", imgPath, err)
}

When it happens

Trigger: f.AddPicture(sheet, cell, "photo.webp", opts), f.AddPictureFromBytes with a name ending in an unsupported extension, f.SetSheetBackground with a .xlsx or .svg file, or AddHeaderFooterImage with an unsupported type.

Common situations: Using modern formats like webp or avif, accidentally passing a spreadsheet/zip path instead of an image path (as in the background test), uppercase extensions are fine but wrong extensions like .ico are not.

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/65578240ea319265. Report an issue: GitHub.