Yalantis/uCrop · error · CImgIOException

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

Error message

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

What it means

load_cimg() first reads a header line expected to decode as '<N><separator><pixeltype><separator><endian>'; if sscanf extracts fewer than 2 fields it concludes the stream is not a CImg-format file and throws (CImg.h:66801). Despite the message, the file usually exists — its content just isn't a valid .cimg header.

Source

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

                                    "load_cimg(): Specified filename is (null).",
                                    cimglist_instance);

      const ulongT cimg_iobuffer = (ulongT)24*1024*1024;
      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 = 0, W, H, D, C;
      cimg_uint64 csiz;
      int i, err;
      do {
        j = 0; while ((i=std::fgetc(nfile))!='\n' && i>=0 && j<255) tmp[j++] = (char)i; tmp[j] = 0;
      } while (*tmp=='#' && i>=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(): File or 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;
      assign(N);
      _cimg_load_cimg_case("bool",0,0,cimg_uint8);
      _cimg_load_cimg_case("uint8","unsigned_char","uchar",cimg_uint8);
      _cimg_load_cimg_case("int8",0,0,cimg_int8);
      _cimg_load_cimg_case("char",0,0,char);
      _cimg_load_cimg_case("uint16","unsigned_short","ushort",cimg_uint16);
      _cimg_load_cimg_case("int16","short",0,cimg_int16);
      _cimg_load_cimg_case("uint32","unsigned_int","uint",cimg_uint32);
      _cimg_load_cimg_case("int32","int",0,cimg_int32);
      _cimg_load_cimg_case("unsigned_long","ulong",0,cimg_ulong);
      _cimg_load_cimg_case("long",0,0,cimg_long);
      _cimg_load_cimg_case("uint64","unsigned_int64",0,cimg_uint64);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Verify the file is genuinely CImg format: first line must be like '3 unsigned_char little_endian'.
  2. Check you are not loading an HTML error page or empty file: inspect first bytes.
  3. Use the loader matching the actual format (CImg::load_png, load_raw, etc.) or re-export the data as .cimg.
  4. Re-transfer the file in binary mode to avoid header corruption.

Example fix

// before
imgs.load_cimg(url.c_str()); // may be a saved 404 page

// after
std::ifstream f(url, std::ios::binary);
char head[64] = {0};
f.read(head, 63);
unsigned n; char ptype[64];
if (std::sscanf(head, "%u %63s", &n, ptype) >= 2) imgs.load_cimg(url.c_str());
else imgs.load(url.c_str()); // fall back to format auto-detection
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 {
  imgs.load_cimg(path);
} catch (cimg_library::CImgIOException& e) {
  if (!looksLikeCimg(path))
    imgs.load(path); // fall back to extension-based format detection
  else throw;
}

Prevention

When it happens

Trigger: Calling CImgList::load_cimg() on a file in a different format (PNG, raw, TIFF), an empty or HTML error-page saved as .cimg, or a .cimg file whose first line was stripped/truncated.

Common situations: Wrong file passed to the loader after a rename; downloading a dataset URL that returned a 404 page saved to disk; text-mode conversion inserting CRLF or BOM into the header; mixing up .cimg with .cimg.gz.

Related errors

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