Yalantis/uCrop · error · CImgInstanceException

atXY(): Empty instance.

Error message

atXY(): Empty instance.

What it means

Reported by CImg<T>::atXY(int,int,int,int,const T&) when the instance has no pixels: the operator() lookup cannot be performed on an empty (unassigned or zero-size) image, and the Dirichlet out_value overload cannot substitute for a nonexistent pixel store.

Source

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

    T& atXY(const int x, const int y, const int z, const int c, const T& out_value) {
      return (x<0 || y<0 || x>=width() || y>=height())?(cimg::temporary(out_value)=out_value):(*this)(x,y,z,c);
    }

    //! Access to a pixel value, using Dirichlet boundary conditions for the X and Y coordinates \const.
    T atXY(const int x, const int y, const int z, const int c, const T& out_value) const {
      return (x<0 || y<0 || x>=width() || y>=height())?out_value:(*this)(x,y,z,c);
    }

    //! Access to a pixel value, using Neumann boundary conditions for the X and Y-coordinates.
    /**
       Similar to atX(int,int,int,int), except that boundary checking is performed both on X and Y-coordinates.
       \note
       - If you know your image instance is \e not empty, you may rather use the slightly faster method
         \c _atXY(int,int,int,int).
     **/
    T& atXY(const int x, const int y, const int z=0, const int c=0) {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atXY(): Empty instance.",
                                    cimg_instance);
      return _atXY(x,y,z,c);
    }

    T& _atXY(const int x, const int y, const int z=0, const int c=0) {
      return (*this)(cimg::cut(x,0,width() - 1),
                     cimg::cut(y,0,height() - 1),z,c);
    }

    //! Access to a pixel value, using Neumann boundary conditions for the X and Y-coordinates \const.
    const T& atXY(const int x, const int y, const int z=0, const int c=0) const {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atXY(): Empty instance.",
                                    cimg_instance);
      return _atXY(x,y,z,c);
    }

View on GitHub (pinned to f788b534b4)

Solutions

1. Check img.is_empty() before calling atXY().
2. Validate that the load/processing step populated the image (dimensions > 0).
3. Use _atXY() on paths where non-emptiness is already guaranteed.

Example fix

// before
float v = img.atXY(x, y); // throws if empty
// after
if (!img.is_empty()) { float v = img.atXY(x, y); } else { /* fallback */ }

if (img && !img.is_empty()) { T v = img.atXY(x, y); }

try {
  T v = img.atXY(x, y);
} catch (CImgInstanceException& e) {
  // empty image: return default or log
}

When it happens

Trigger: Calling img.atXY(x,y,z,c) on an image of size 0 (default-constructed, failed load, or empty crop).

Common situations: Sampling from an image that failed to decode; algorithm assuming a prior step always produced pixels.

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

• at(): 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/b303ec29d0f6d521. Report an issue: GitHub.