Yalantis/uCrop · error · CImgIOException

load(): Failed to recognize format of file '%s'.

Error message

load(): Failed to recognize format of file '%s'.

What it means

The file opened successfully but every format-specific loader (including load_other, which dispatches by magic number/extension) threw CImgIOException, so load() reports that it cannot recognize the file format. The library opens the file fine but no plugin/loader claims it.

Source

Thrown at ucrop/src/main/jni/CImg.h:56614

          else if (!cimg::strcasecmp(f_type,"jpg")) load_jpeg(filename);
          else if (!cimg::strcasecmp(f_type,"pan")) load_pandore(filename);
          else if (!cimg::strcasecmp(f_type,"png")) load_png(filename);
          else if (!cimg::strcasecmp(f_type,"tif")) load_tiff(filename);
          else if (!cimg::strcasecmp(f_type,"gif")) load_gif_external(filename);
          else if (!cimg::strcasecmp(f_type,"dcm")) load_medcon_external(filename);
          else if (!cimg::strcasecmp(f_type,"webp")) load_webp(filename);
          else if (!cimg::strcasecmp(f_type,"jxl")) load_jxl(filename);
          else is_loaded = false;
        } catch (CImgIOException&) { is_loaded = false; }
      }

      // If nothing loaded, try to load file with other means.
      if (!is_loaded) {
        try {
          load_other(filename);
        } catch (CImgIOException&) {
          cimg::exception_mode(omode);
          throw CImgIOException(_cimg_instance
                                "load(): Failed to recognize format of file '%s'.",
                                cimg_instance,
                                filename);
        }
      }
      cimg::exception_mode(omode);
      return *this;
    }

    //! Load image from a file \newinstance.
    static CImg<T> get_load(const char *const filename) {
      return CImg<T>().load(filename);
    }

    //! Load image from an ascii file.
    /**
       \param filename Filename, as a C -string.
    **/

View on GitHub (pinned to f788b534b4)

Solutions

  1. Check the file's magic bytes (first 2-8 bytes) to confirm it is a format CImg supports (BMP/PNG/JPEG/etc.).
  2. Convert/transcode the image to PNG or JPEG with another decoder (BitmapFactory on Android) before loading.
  3. Load pixels manually (decode elsewhere) and construct the CImg from the raw buffer.
  4. Re-enable or register the matching image format library (e.g. ImageMagick/Other plugins via cimg_use_* defines) if the format is supported when configured.

Example fix

// before
img.load(path); // HEIC file -> unrecognized
// after
if (!hasSupportedMagic(path)) {
  decodeWithBitmapAndConvertToPng(path, tmpPng);
  path = tmpPng;
}
img.load(path);
Defensive patterns

Strategy: fallback

Validate before calling

bool magicSupported(const char* p){ std::ifstream f(p,std::ios::binary); char b[8]={0}; f.read(b,8); return !strncmp(b,"\x89PNG",4)||!strncmp(b,"\xFF\xD8",2)||!strncmp(b,"BM",2)||!strncmp(b,"GIF",3); }

Try / catch

try { img.load(path); } catch (cimg_library::CImgIOException&) { // unknown format: transcode via platform decoder then retry
  transcodeToPng(path, tmp); img.load(tmp); }

Prevention

When it happens

Trigger: img.load(path) on a file whose magic bytes match no supported format (e.g. WEBP/HEIC in builds without those loaders), a truncated/corrupt image, or a text/JSON file passed to the image loader.

Common situations: Android saves HEIC/WEBP by default; uCrop's bundled CImg lacks those loaders. Also hitting this with broken partial downloads or files with wrong extensions.

Related errors

AI-assisted analysis of Yalantis/uCrop@f788b534b4 (2026-09-08). Data as JSON: /api/errors/b842a7dbc287908e. Report an issue: GitHub.