Yalantis/uCrop · error · CImgInstanceException

at(): Empty instance.

Error message

at(): Empty instance.

What it means

CImg::at(offset) provides pixel access with Neumann boundary clamping on the offset, but first requires a non-empty image instance. If the image has no pixels (is_empty(), e.g. _data==null or size 0), it throws CImgInstanceException instead of returning a value.

Source

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

    }

    //! Access to a pixel value at a specified offset, using Neumann boundary conditions.
    /**
       Return a reference to the pixel value of the image instance located at a specified \c offset,
       or to the nearest pixel location in the image instance in case of out-of-bounds access.
       \param offset Offset to the desired pixel value.
       \note
       - Similar to at(int,const T), except that an out-of-bounds access returns the value of the
         nearest pixel in the image instance, regarding the specified offset, i.e.
         - If \c offset<0, then \c img[0] is returned.
         - If \c offset>=img.size(), then \c img[img.size() - 1] is returned.
       - Due to the additional boundary checking operation, this method is slower than operator()(). Use it when
         you are \e not sure about the validity of the specified pixel offset.
       - If you know your image instance is \e not empty, you may rather use the slightly faster method \c _at(int).
     **/
    T& at(const int offset) {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "at(): Empty instance.",
                                    cimg_instance);
      return _at(offset);
    }

    T& _at(const int offset) {
      const unsigned int siz = (unsigned int)size();
      return (*this)[offset<0?0:(unsigned int)offset>=siz?siz - 1:offset];
    }

    //! Access to a pixel value at a specified offset, using Neumann boundary conditions \const.
    const T& at(const int offset) const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "at(): Empty instance.",
                                    cimg_instance);
      return _at(offset);
    }

View on GitHub (pinned to f788b534b4)

Solutions

1. Check img.is_empty() before calling at() and handle the empty case.
2. Verify the load/assign call that should populate the image succeeded (check return value / file existence).
3. Use at() only after successful initialization; for guaranteed non-empty code paths use the faster _at(offset).

Example fix

// before
float v = img.at(idx); // throws if img empty
// after
if (!img.is_empty()) { float v = img.at(idx); } else { /* handle empty image */ }

if (img.is_empty()) { /* handle empty before calling at() */ }

try {
  T v = img.at(offset);
} catch (CImgInstanceException& e) {
  // image empty: fallback value or error path
}

When it happens

Trigger: Calling img.at(offset) on an image constructed with CImg<T>() default constructor, or one whose width/height/depth/spectrum are all effectively zero.

Common situations: Image failed to load (empty result from load()) but code proceeds to read pixels; early return path left image un-assigned; crop/filter operation produced a 0-size image.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• atXY(): Empty instance.
• atXYZ(): Empty instance.
• atX(): Empty instance.
• operator(): Invalid pixel request, at coordinates (%d,%d,%d,
• data(): Invalid pointer request, at coordinates (%u,%u,%u,%u

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