Yalantis/uCrop · error · CImgIOException

load_analyze(): Invalid header size (%u) specified in file '

Error message

load_analyze(): Invalid header size (%u) specified in file '%s'.

What it means

After opening the Analyze/NIfTI header, load_analyze() reads the first 4-byte 'sizeof_hdr' field. A valid header is at least 128 bytes (Analyze7.5 uses 348, NIfTI-1 uses 348). If the value read is below 128 it throws; >=4096 only triggers byte-order inversion, not this error. This almost always means the file is not actually an Analyze7.5/NIfTI file.

Source

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

        } else if (!cimg::strcasecmp(ext,"img")) { // File is an Analyze data file
          nfile = cimg::fopen(filename,"rb");
          cimg_snprintf(body._data + len,body._width - len,".hdr");
          nfile_header = cimg::fopen(body,"rb");
        } else nfile_header = nfile = cimg::fopen(filename,"rb"); // File is a Niftii file
      } else nfile_header = nfile = file; // File is a Niftii file
      if (!nfile || !nfile_header)
        throw CImgIOException(_cimg_instance
                              "load_analyze(): Invalid Analyze7.5 or NIFTI header in file '%s'.",
                              cimg_instance,
                              filename?filename:"(FILE*)");

      // Read header.
      bool endian = false;
      unsigned int header_size;
      cimg::fread(&header_size,1,nfile_header);
      if (header_size>=4096) { endian = true; cimg::invert_endianness(header_size); }
      if (header_size<128)
        throw CImgIOException(_cimg_instance
                              "load_analyze(): Invalid header size (%u) specified in file '%s'.",
                              cimg_instance,
                              header_size,filename?filename:"(FILE*)");

      unsigned char *const header = new unsigned char[header_size];
      const size_t header_size_read = cimg::fread(header + 4,header_size - 4,nfile_header);
      if (header_size_read!=header_size - 4)
        throw CImgIOException(_cimg_instance
                              "load_analyze(): Cannot read header (of size %u) in file '%s'.",
                              cimg_instance,
                              header_size,filename?filename:"(FILE*)");

      if (!file && nfile_header!=nfile) cimg::fclose(nfile_header);
      if (endian) {
        cimg::invert_endianness((short*)(header + 40),5);
        cimg::invert_endianness((short*)(header + 70),1);
        cimg::invert_endianness((short*)(header + 72),1);
        cimg::invert_endianness((float*)(header + 76),4);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Check the file's first 4 bytes: sizeof_hdr must be 348 (NIfTI-1/Analyze) — validate before calling.
  2. Re-download or re-export the file; verify non-zero, complete size.
  3. Confirm the file is really Analyze7.5/NIfTI-1, not DICOM/NIfTI-2; use the matching loader.
  4. If bytes look swapped, the endianness handling covers >=4096 only for sizes; a corrupt header still needs re-export.
  5. Catch CImgIOException and fall back to format sniffing (e.g. try load_nii/load_analyze or file magic).

Example fix

// before
img.load("mystery.img"); // header_size < 128 -> throw
// after
unsigned int h; std::FILE* f = std::fopen("mystery.img","rb");
std::fread(&h,4,1,f); std::fclose(f);
if (h == 348) img.load_analyze("mystery.img"); else throw std::runtime_error("not Analyze/NIfTI-1");
Defensive patterns

Strategy: validation

Validate before calling

bool looksLikeAnalyzeNifti(const char* p) {
  std::FILE* f = std::fopen(p, "rb"); if (!f) return false;
  unsigned int h = 0; bool ok = std::fread(&h, 4, 1, f) == 1; std::fclose(f);
  if (!ok) return false;
  unsigned int sw = h; cimg::invert_endianness(sw);
  return h >= 128 || sw >= 128; // accept either byte order
}

Type guard

bool hasValidHeaderSize(unsigned int header_size) { return header_size >= 128 && header_size < 4096 * 64; }

Try / catch

try { img.load_analyze(path); }
catch (CImgIOException& e) { fprintf(stderr, "Bad sizeof_hdr field: %s\n", e.what()); /* try other loader */ }

Prevention

When it happens

Trigger: load_analyze() given a file whose first 4 bytes, interpreted as a little-endian uint32, are < 128 — e.g. a truncated, empty, text, or wrongly-renamed file passed to CImg::load("x.img") or load_analyze().

Common situations: Files downloaded incompletely; a non-medical file renamed to .hdr/.img; zero-byte placeholder files; loading a NIfTI-2 (.nii2, 540-byte different layout) or other format via the Analyze path.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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