{"record":{"id":"65578240ea319265","repo":"qax-os/excelize","slug":"unsupported-image-extension","errorCode":null,"errorMessage":"unsupported image extension","messagePattern":"unsupported image extension","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"errors.go","lineNumber":90,"sourceCode":"\t// ErrFillPatternColor defined the error message on receive an invalid fill\n\t// color for 'pattern' type.\n\tErrFillPatternColor = errors.New(\"fill color value must be empty or an array of one color for 'pattern' type\")\n\t// ErrFillPattern defined the error message on receive an invalid fill\n\t// pattern.\n\tErrFillPattern = errors.New(\"fill pattern value must be between 0 and 18\")\n\t// ErrFontLength defined the error message on the length of the font\n\t// family name overflow.\n\tErrFontLength = fmt.Errorf(\"the length of the font family name must be less than or equal to %d\", MaxFontFamilyLength)\n\t// ErrFontSize defined the error message on the size of the font is invalid.\n\tErrFontSize = fmt.Errorf(\"font size must be an integer from %d to %d points\", MinFontSize, MaxFontSize)\n\t// ErrFormControlValue defined the error message for receiving a scroll\n\t// value exceeds limit.\n\tErrFormControlValue = fmt.Errorf(\"scroll value must be an integer from 0 to %d\", MaxFormControlValue)\n\t// ErrGroupSheets defined the error message on group sheets.\n\tErrGroupSheets = errors.New(\"group worksheet must contain an active worksheet\")\n\t// ErrImgExt defined the error message on receive an unsupported image\n\t// extension.\n\tErrImgExt = errors.New(\"unsupported image extension\")\n\t// ErrInvalidFormula defined the error message on receive an invalid\n\t// formula.\n\tErrInvalidFormula = errors.New(\"formula not valid\")\n\t// ErrMaxFilePathLength defined the error message on receive the file path\n\t// length overflow.\n\tErrMaxFilePathLength = fmt.Errorf(\"file path length exceeds maximum limit %d characters\", MaxFilePathLength)\n\t// ErrMaxRowHeight defined the error message on receive an invalid row\n\t// height.\n\tErrMaxRowHeight = fmt.Errorf(\"the height of the row must be less than or equal to %d points\", MaxRowHeight)\n\t// ErrMaxRows defined the error message on receive a row number exceeds\n\t// maximum limit.\n\tErrMaxRows = errors.New(\"row number exceeds maximum limit\")\n\t// ErrNameLength defined the error message on receiving the defined name or\n\t// table name length exceeds the limit.\n\tErrNameLength = fmt.Errorf(\"the name length exceeds the %d characters limit\", MaxFieldLength)\n\t// ErrMaxGraphicAltTextLength defined the error message on receiving the\n\t// graphic alt text length exceeds the limit.\n\tErrMaxGraphicAltTextLength = fmt.Errorf(\"the alt text length exceeds the %d characters limit\", MaxGraphicAltTextLength)","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/qax-os/excelize/blob/f2483381fbfbe432a6baa98d48a1c277183f3285/errors.go#L72-L108","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Convert the image to a supported format (png, jpeg, gif, bmp, tiff, emf, or wmf) before adding it.","Verify the file path points to an actual image, not another document type.","For AddPictureFromBytes, set the Ext field of the Image options to a supported extension matching the bytes.","Check the extension with filepath.Ext against the supported list before calling the API."],"exampleFix":"// before\nerr := f.AddPicture(\"Sheet1\", \"A1\", \"logo.webp\", opts)\n// after\n// convert logo.webp to logo.png first\nerr := f.AddPicture(\"Sheet1\", \"A1\", \"logo.png\", opts)","handlingStrategy":"validation","validationCode":"var supported = map[string]bool{\"bmp\": true, \"gif\": true, \"jpg\": true, \"jpeg\": true, \"png\": true, \"tif\": true, \"tiff\": true, \"emf\": true, \"wmf\": true}\next := strings.TrimPrefix(strings.ToLower(filepath.Ext(path)), \".\")\nif !supported[ext] {\n    return fmt.Errorf(\"unsupported image extension: %s\", ext)\n}","typeGuard":"func isSupportedImage(path string) bool {\n    switch strings.ToLower(filepath.Ext(path)) {\n    case \".bmp\", \".gif\", \".jpg\", \".jpeg\", \".png\", \".tif\", \".tiff\", \".emf\", \".wmf\":\n        return true\n    }\n    return false\n}","tryCatchPattern":"err := f.AddPicture(sheet, cell, imgPath, opts)\nif errors.Is(err, excelize.ErrImgExt) {\n    // convert the image to PNG and retry, or report to the user\n    return fmt.Errorf(\"image %q must be png/jpg/gif/bmp/tiff/emf/wmf: %w\", imgPath, err)\n}","preventionTips":["Normalize uploads to PNG or JPEG before passing to the library.","Check filepath.Ext against the supported list before calling any picture API.","For AddPictureFromBytes, ensure the Ext/name extension matches the actual bytes.","Sanitize user-supplied image paths to reject webp/avif/svg and non-image files."],"tags":["go","excelize","image","file-format","validation"],"backgroundTag":"unsupported-file-format","analyzedSha":"f2483381fbfbe432a6baa98d48a1c277183f3285","analyzedAt":"2026-09-02T01:26:19.299Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T06:17:21.866Z"}