Yalantis/uCrop · error · CImgIOException

save_webp(): Failed to encode image to file '%s'.

Error message

save_webp(): Failed to encode image to file '%s'.

What it means

After WebPEncodeRGB/WebPEncodeRGBA returns, CImg checks whether the encoder produced any data (imgData is null). A null buffer means libwebp failed to encode the image (e.g. invalid dimensions, out of memory, or unsupported pixel setup), so CImg throws CImgIOException before writing the file.

Source

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

      uint8_t *ptr = rgbaBuffer._data;
      cimg_forY(*this,y) {
        cimg_forX(*this,x) {
          *(ptr++) = (T)*(ptr_r++);
          *(ptr++) = (T)*(ptr_g++);
          *(ptr++) = (T)*(ptr_b++);
          if (ptr_a) *(ptr++) = (T)*(ptr_a++);
        }
      }
      uint8_t *imgData = NULL;
      const int stride = _width*_spectrum*sizeof(uint8_t);
      size_t size = 0;
      if (_spectrum==3) {
        size = WebPEncodeRGB(rgbaBuffer._data, _width, _height, stride, (float)quality, &imgData);
      } else {
        size = WebPEncodeRGBA(rgbaBuffer._data, _width, _height, stride, (float)quality, &imgData);
      }
      if (!imgData) {
        throw CImgIOException(_cimg_instance
                              "save_webp(): Failed to encode image to file '%s'.",
                              cimg_instance,
                              filename);
      }
      cimg::fwrite(imgData, size, file);
      cimg::fclose(file);
      WebPFree(imgData);
      return *this;
#endif
    }

    //! Save image as a JPEG file.
    /**
      \param filename Filename, as a C-string.
      \param quality Image quality (in %)
    **/
    const CImg<T>& save_jpeg(const char *const filename, const unsigned int quality=100) const {
      return _save_jpeg(0,filename,quality);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Verify _width>0 and _height>0 before saving; a zero-dimension image cannot be encoded.
  2. Check available memory and image size; reduce image dimensions (resize) before WebP encoding.
  3. Lower the quality parameter is unlikely to help; instead confirm the webp build is intact and dimensions are sane, then retry or use another format (save_png).

Example fix

// before
img.save_webp("huge.webp");
// after
if (img.width() == 0 || img.height() == 0) throw std::runtime_error("empty image");
CImg<float> small = img.get_resize(4096, 4096, -100, -100);
small.save_webp("huge.webp");
Defensive patterns

Strategy: try-catch

Validate before calling

if (img.is_empty() || img.width() == 0 || img.height() == 0) {
  throw std::runtime_error("cannot save empty image as webp");
}

Try / catch

try {
  img.save_webp("out.webp");
} catch (const cimg_library::CImgIOException &e) {
  std::fprintf(stderr, "webp encode failed: %s\n", e.what());
  img.save_png("out.png"); // fallback format
}

Prevention

When it happens

Trigger: Calling save_webp() when WebPEncodeRGB/RGBA returns size==0 and imgData==nullptr — typically from enormous width*height (memory allocation failure in libwebp) or invalid image dimensions.

Common situations: Saving extremely large images that exceed memory limits, images with zero width/height, or environments where the webp encoder cannot allocate the output buffer. Sometimes seen with corrupted/undimensioned image instances.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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