Yalantis/uCrop · error · CImgIOException

load_png(): Failed to initialize 'png_ptr' structure for fil

Error message

load_png(): Failed to initialize 'png_ptr' structure for file '%s'.

What it means

Thrown by CImg<T>::load_png() when libpng's png_create_read_struct() returns null, i.e. libpng could not allocate or initialize its core decode structure for the named file — almost always an out-of-memory condition or a libpng version/ABI problem.

Source

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

      std::FILE *nfile = file?file:cimg::fopen(nfilename,"rb");
#endif
      unsigned char pngCheck[8] = {};
      cimg::fread(pngCheck,8,(std::FILE*)nfile);
      if (png_sig_cmp(pngCheck,0,8)) {
        if (!file) cimg::fclose(nfile);
        throw CImgIOException(_cimg_instance
                              "load_png(): Invalid PNG file '%s'.",
                              cimg_instance,
                              nfilename?nfilename:"(FILE*)");
      }

      // Setup PNG structures for read.
      png_voidp user_error_ptr = 0;
      png_error_ptr user_error_fn = 0, user_warning_fn = 0;
      png_structp png_ptr = png_create_read_struct(PNG_LIBPNG_VER_STRING,user_error_ptr,user_error_fn,user_warning_fn);
      if (!png_ptr) {
        if (!file) cimg::fclose(nfile);
        throw CImgIOException(_cimg_instance
                              "load_png(): Failed to initialize 'png_ptr' structure for file '%s'.",
                              cimg_instance,
                              nfilename?nfilename:"(FILE*)");
      }
      png_infop info_ptr = png_create_info_struct(png_ptr);
      if (!info_ptr) {
        if (!file) cimg::fclose(nfile);
        png_destroy_read_struct(&png_ptr,(png_infopp)0,(png_infopp)0);
        throw CImgIOException(_cimg_instance
                              "load_png(): Failed to initialize 'info_ptr' structure for file '%s'.",
                              cimg_instance,
                              nfilename?nfilename:"(FILE*)");
      }
      png_infop end_info = png_create_info_struct(png_ptr);
      if (!end_info) {
        if (!file) cimg::fclose(nfile);
        png_destroy_read_struct(&png_ptr,&info_ptr,(png_infopp)0);
        throw CImgIOException(_cimg_instance

View on GitHub (pinned to f788b534b4)

Solutions

Check available memory; reduce concurrent allocations or image workloads.
Rebuild against a consistent libpng version (headers and linked library must match).
Upgrade libpng to a current version (very old libpng versions had init issues).
If transient OOM, retry the load after freeing memory.

Example fix

// before
img.load_png("big.png"); // fails under memory pressure
// after
if (img.width() && img.height()) img.clear(); // release memory first
img.load_png("big.png");

Defensive patterns

Strategy: retry

Validate before calling

// no pre-call validation possible; ensure libpng is linked and heap has headroom

Try / catch

try { img.load_png(path); }
catch (CImgIOException &e) {
  std::fprintf(stderr, "libpng init failed: %s\n", e.what());
}

Prevention

Keep libpng headers and binaries from the same version/build
Avoid loading many large images concurrently
Monitor memory before attempting large image decodes

When it happens

Trigger: Out-of-memory or heavily fragmented heap when allocating libpng's read struct; a libpng version mismatch between headers and the linked runtime library.

Common situations: Memory-constrained environments (Android NDK, embedded) where allocation fails; mixing libpng headers from one version with a shared libpng of an incompatible version.

Related errors

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