Yalantis/uCrop · error · CImgIOException

load_gzip_external(): Failed to load file

Error message

load_gzip_external(): Failed to load file '%s' with external command 'gunzip'.

What it means

load_gzip_external() runs `"gunzip" -c "<file>" > <tmpfile>` via cimg::system(); a non-zero exit status throws this CImgIOException. The gunzip tool was found and launched, but the decompression command failed.

Solutions

Run the same gunzip command manually to see the real failure
Verify gzip integrity with `gzip -t file.gz` before loading
Ensure the temp output directory is writable and gunzip exists (cimg::gunzip_path())
Decompress in-process with zlib (gzread) into memory and load via CImg from a temp plain file, avoiding external tools

Example fix

// before
img.load_gzip_external("data.cimg.gz"); // gunzip exit != 0
// after
if (cimg::system("gzip -t data.cimg.gz") == 0) {
  img.load_gzip_external("data.cimg.gz");
} else {
  // decompress with zlib in-process and load the plain file
  decompress_zlib_to("data.cimg.gz", "/tmp/data.cimg");
  img.load_cimg("/tmp/data.cimg");
}

Defensive patterns

Strategy: try-catch

Validate before calling

// test archive integrity and tool availability first
bool gz_ok = cimg::system("gzip -t data.cimg.gz") == 0;
bool tool_ok = cimg::gunzip_path()[0] != '\0';

Try / catch

try {
  img.load_gzip_external(path);
} catch (CImgIOException& e) {
  // decompress in-process with zlib, then load plain file
  gunzip_to_temp(path, "/tmp/out.cimg");
  img.load_cimg("/tmp/out.cimg");
}

Prevention

Validate .gz integrity (gzip -t) before loading
Confirm gunzip exists on PATH in the target environment
Check temp directory writability and disk space
Prefer zlib in-process decompression on constrained platforms

When it happens

Trigger: Corrupt or truncated .gz payload (gunzip exits non-zero), gunzip not actually on PATH in a way cimg::gunzip_path() resolves oddly, or shell redirection failing (unwritable temp directory).

Common situations: Partially uploaded .gz files; files compressed with unsupported variants; restricted Android/app environments where exec of external binaries is blocked or PATH is empty; full temp filesystem.

Related errors

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

Appendix: source

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

      do {
        if (!cimg::strcasecmp(ext,"gz")) {
          if (*ext2) cimg_snprintf(filename_tmp,filename_tmp._width,"%s%c%s.%s",
                                   cimg::temporary_path(),cimg_file_separator,cimg::filenamerand(),ext2);
          else cimg_snprintf(filename_tmp,filename_tmp._width,"%s%c%s",
                             cimg::temporary_path(),cimg_file_separator,cimg::filenamerand());
        } else {
          if (*ext) cimg_snprintf(filename_tmp,filename_tmp._width,"%s%c%s.%s",
                                  cimg::temporary_path(),cimg_file_separator,cimg::filenamerand(),ext);
          else cimg_snprintf(filename_tmp,filename_tmp._width,"%s%c%s",
                             cimg::temporary_path(),cimg_file_separator,cimg::filenamerand());
        }
      } while (cimg::path_exists(filename_tmp));
      cimg_snprintf(command,command._width,"\"%s\" -c \"%s\" > \"%s\"",
                    cimg::gunzip_path(),
                    CImg<charT>::string(filename)._system_strescape().data(),
                    CImg<charT>::string(filename_tmp)._system_strescape().data());
      if (cimg::system(command)!=0)
        throw CImgIOException(_cimg_instance
                              "load_gzip_external(): Failed to load file '%s' with external command 'gunzip'.",
                              cimg_instance,
                              filename);
      if (!cimg::path_exists(filename_tmp)) {
        cimg::fclose(cimg::fopen(filename,"r"));
        throw CImgIOException(_cimg_instance
                              "load_gzip_external(): Failed to load file '%s' with external command 'gunzip'.",
                              cimg_instance,
                              filename);

      }
      load(filename_tmp);
      std::remove(filename_tmp);
      return *this;
    }

    //! Load gzipped image file, using external tool 'gunzip' \newinstance.
    static CImg<T> get_load_gzip_external(const char *const filename) {

View on GitHub (pinned to f788b534b4)