Yalantis/uCrop · error · CImgIOException

load_cimg(): CImg header not found in file '%s'.

Error message

load_cimg(): CImg header not found in file '%s'.

What it means

Single-image CImg<T>::load_cimg() reads the first line expecting '<N><sep><pixeltype><sep><endian>'; if sscanf extracts fewer than 2 fields it throws CImgIOException saying the CImg header was not found (CImg.h:66979). The stream is not a valid .cimg file.

Source

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

      unsigned int
        nn0 = std::min(n0,n1), nn1 = std::max(n0,n1),
        nx0 = std::min(x0,x1), nx1 = std::max(x0,x1),
        ny0 = std::min(y0,y1), ny1 = std::max(y0,y1),
        nz0 = std::min(z0,z1), nz1 = std::max(z0,z1),
        nc0 = std::min(c0,c1), nc1 = std::max(c0,c1);

      std::FILE *const nfile = file?file:cimg::fopen(filename,"rb");
      bool loaded = false, endian = cimg::endianness();
      CImg<charT> tmp(256), str_pixeltype(256), str_endian(256);
      *tmp = *str_pixeltype = *str_endian = 0;
      unsigned int j, N, W, H, D, C;
      int i, err;
      j = 0; while ((i=std::fgetc(nfile))!='\n' && i!=EOF && j<256) tmp[j++] = (char)i; tmp[j] = 0;
      err = cimg_sscanf(tmp,"%u%*c%255[A-Za-z123468_]%*c%255[sA-Za-z_ ]",
                        &N,str_pixeltype._data,str_endian._data);
      if (err<2) {
        if (!file) cimg::fclose(nfile);
        throw CImgIOException(_cimglist_instance
                              "load_cimg(): CImg header not found in file '%s'.",
                              cimglist_instance,
                              filename?filename:"(FILE*)");
      }
      if (!cimg::strncasecmp("little",str_endian,6)) endian = false;
      else if (!cimg::strncasecmp("big",str_endian,3)) endian = true;
      nn1 = n1==~0U?N - 1:n1;
      if (nn1>=N)
        throw CImgArgumentException(_cimglist_instance
                                    "load_cimg(): Invalid specified coordinates [%u](%u,%u,%u,%u) -> [%u](%u,%u,%u,%u) "
                                    "because file '%s' contains only %u images.",
                                    cimglist_instance,
                                    n0,x0,y0,z0,c0,n1,x1,y1,z1,c1,filename?filename:"(FILE*)",N);
      assign(1 + nn1 - n0);
      _cimg_load_cimg_case2("bool",0,0,cimg_uint8);
      _cimg_load_cimg_case2("uint8","unsigned char","uchar",cimg_uint8);
      _cimg_load_cimg_case2("int8",0,0,cimg_int8);
      _cimg_load_cimg_case2("char",0,0,char);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Confirm the first line is 'W H D C'-style stream header like '1 unsigned_char little_endian' for the image list; fix or re-export the file.
  2. Use the format-appropriate loader (CImg::load / load_png / load_raw) if the file is not .cimg.
  3. Re-transfer in binary mode to avoid header mangling; strip any BOM.
  4. If the file is .cimg.gz, decompress it or enable zlib support first.

Example fix

// before
img.load_cimg(maybeGzipPath); // not a plain .cimg

// after
std::string path = maybeGzipPath;
if (hasGzipMagic(path)) path = gunzipToTemp(path);
std::ifstream f(path, std::ios::binary);
char head[64] = {0}; f.read(head, 63);
unsigned n; char pt[64];
if (std::sscanf(head, "%u %63s", &n, pt) >= 2) img.load_cimg(path.c_str());
else img.load(path.c_str());
Defensive patterns

Strategy: validation

Validate before calling

bool looksLikeCimg(const char* path) {
  std::FILE* f = std::fopen(path, "rb"); if (!f) return false;
  char line[256] = {0};
  bool got = std::fgets(line, sizeof line, f) != nullptr;
  std::fclose(f);
  unsigned N; char pt[64], en[64];
  return got && std::sscanf(line, "%u %63[A-Za-z123468_] %63[sA-Za-z_ ]", &N, pt, en) >= 2;
}

Try / catch

try {
  img.load_cimg(path);
} catch (cimg_library::CImgIOException& e) {
  if (!looksLikeCimg(path)) img.load(path); // format auto-detection fallback
  else throw;
}

Prevention

When it happens

Trigger: Calling img.load_cimg(filename) on a non-CImg file (PNG/JPEG/raw), an empty file, or a .cimg whose first line was truncated, BOM-prefixed, or CRLF-mangled.

Common situations: Wrong extension/format mix-up; interrupted transfer; downloading a dataset URL that served an error page; using a gzip-compressed file directly instead of via load_cimg with zlib.

Related errors

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