Yalantis/uCrop · error · CImgInstanceException

atX(): Empty instance.

Error message

atX(): Empty instance.

What it means

CImg::atX(x,y,z,c) clamps only the X coordinate to image bounds (Y,Z,C are unchecked) but first requires a non-empty image. On an empty instance it throws CImgInstanceException because there are no valid coordinates to clamp to.

Source

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

       Return a reference to the pixel value of the image instance located at (\c x,\c y,\c z,\c c),
       or to the nearest pixel location in the image instance in case of out-of-bounds access along the X-axis.
       \param x X-coordinate of the pixel value.
       \param y Y-coordinate of the pixel value.
       \param z Z-coordinate of the pixel value.
       \param c C-coordinate of the pixel value.
       \note
       - Similar to at(int,int,int,int,const T), except that an out-of-bounds access returns the value of the
         nearest pixel in the image instance, regarding the specified X-coordinate.
       - 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 coordinates.
       - If you know your image instance is \e not empty, you may rather use the slightly faster method
         \c _at(int,int,int,int).
       \warning
       - There is \e no boundary checking performed for the Y,Z and C-coordinates, so they must be inside image bounds.
     **/
    T& atX(const int x, const int y=0, const int z=0, const int c=0) {
      if (is_empty())
        throw CImgInstanceException(_cimg_instance
                                    "atX(): Empty instance.",
                                    cimg_instance);
      return _atX(x,y,z,c);
    }

    T& _atX(const int x, const int y=0, const int z=0, const int c=0) {
      return (*this)(x<0?0:(x>=width()?width() - 1:x),y,z,c);
    }

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

View on GitHub (pinned to f788b534b4)

Solutions

1. Check img.is_empty() before calling atX().
2. Confirm the image-producing step (load/crop/assign) succeeded before pixel reads.
3. Remember Y,Z,C are unchecked - validate them yourself even on non-empty images.

Example fix

// before
float v = img.atX(x, y); // throws if img empty
// after
if (img && !img.is_empty()) { float v = img.atX(x, y); }

if (!img.is_empty() && y >= 0 && y < img.height() && z >= 0 && z < img.depth() && c >= 0 && c < img.spectrum()) {
  T v = img.atX(x, y, z, c);
}

try {
  T v = img.atX(x, y);
} catch (CImgInstanceException& e) {
  // empty image fallback
}

When it happens

Trigger: Calling img.atX(x,y,z,c) on a default-constructed or zero-sized image.

Common situations: Downstream code reading pixels after a load failure left the image empty; conditional assignment path skipped; empty crop result passed on.

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.
• atXY(): Empty instance.
• atXYZ(): Empty instance.
• display(): Empty specified image.
• render(): Empty specified image.

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