Yalantis/uCrop · error · CImgIOException

save_gzip_external(): Failed to save file

Error message

save_gzip_external(): Failed to save file '%s' with external command 'gzip'.

What it means

save_gzip_external() runs the gzip executable via cimg::system(); a non-zero exit status means the external compression failed, so it throws CImgIOException for the given filename. Common causes are gzip not installed/not on PATH (cimg::gzip_path() empty or wrong), or the spawned command failing on the escaped file paths.

Solutions

Install gzip (apt-get install gzip / apk add gzip) or ensure it's on PATH.
Verify cimg::gzip_path() resolves to a working binary; set the appropriate path if needed.
Check the target directory is writable and has space.
Replace with in-process compression (zlib) to avoid external dependency.

Example fix

// before
img.save_gzip_external("out.cimg.gz"); // fails if gzip absent
// after
#ifdef cimg_use_zlib
/* use built-in zlib-based save */
#else
if (std::system("gzip --version > /dev/null 2>&1") == 0)
  img.save_gzip_external("out.cimg.gz");
else
  std::fprintf(stderr, "gzip not installed\n");
#endif

Defensive patterns

Strategy: try-catch

Validate before calling

bool gzipAvailable = std::system("gzip --version > /dev/null 2>&1") == 0;
if (gzipAvailable) img.save_gzip_external("out.cimg.gz");

Try / catch

try { img.save_gzip_external(target); }
catch (cimg_library::CImgIOException &e) {
  std::fprintf(stderr, "gzip external save failed: %s\n", e.what());
  img.save("out.cimg"); // fallback: uncompressed
}

Prevention

Install gzip in the deployment image (apt/apk/yum).
Escape or avoid shell-special characters in file paths.
Ensure ample disk space and write permissions in the target directory.
Fall back to uncompressed saving when external tools are unavailable.

When it happens

Trigger: gzip binary missing or not executable on the system; cimg::gzip_path() pointing to a wrong location; shell metacharacters in the temp or target path breaking the quoted command; disk full or permission denied during compression.

Common situations: Docker/CI images without the gzip package; Windows environments where gzip isn't available; sandboxed processes lacking shell access to run the external command.

Related errors

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

Appendix: source

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

        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",
                             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",
                             cimg::temporary_path(),cimg_file_separator,cimg::filenamerand());
        }
      } while (cimg::path_exists(filename_tmp));
      save(filename_tmp);
      cimg_snprintf(command,command._width,"\"%s\" -c \"%s\" > \"%s\"",
                    cimg::gzip_path(),
                    CImg<charT>::string(filename_tmp)._system_strescape().data(),
                    CImg<charT>::string(filename)._system_strescape().data());
      if (cimg::system(command,cimg::gzip_path())!=0)
        throw CImgIOException(_cimg_instance
                              "save_gzip_external(): Failed to save file '%s' with external command 'gzip'.",
                              cimg_instance,
                              filename);
      if (!cimg::path_exists(filename))
        throw CImgIOException(_cimg_instance
                              "save_gzip_external(): Failed to save file '%s' with external command 'gzip'.",
                              cimg_instance,
                              filename);

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

    //! Save image using GraphicsMagick's external binary.
    /**
       \param filename Filename, as a C-string.
       \param quality Image quality (expressed in percent), when the file format supports it.
       \note This method uses \c gm, an external executable binary provided by

View on GitHub (pinned to f788b534b4)