{"record":{"id":"6e6c40c0bc17ebf8","repo":"Yalantis/uCrop","slug":"load-tiff-unable-to-read-sub-images-from-file","errorCode":null,"errorMessage":"load_tiff(): Unable to read sub-images from file '%s' unless libtiff is enabled.","messagePattern":"load_tiff\\(\\): Unable to read sub-images from file '(.+?)' unless libtiff is enabled\\.","errorType":"exception","errorClass":"CImgArgumentException","httpStatus":null,"severity":"error","filePath":"ucrop/src/main/jni/CImg.h","lineNumber":57990,"sourceCode":"     **/\n    CImg<T>& load_tiff(const char *const filename,\n                       const unsigned int first_frame=0, const unsigned int last_frame=~0U,\n                       const unsigned int step_frame=1, unsigned int *const bits_per_value=0,\n                       float *const voxel_size=0, CImg<charT> *const description=0) {\n      if (!filename)\n        throw CImgArgumentException(_cimg_instance\n                                    \"load_tiff(): Specified filename is (null).\",\n                                    cimg_instance);\n\n      const unsigned int\n        nfirst_frame = first_frame<last_frame?first_frame:last_frame,\n        nstep_frame = step_frame?step_frame:1;\n      unsigned int nlast_frame = first_frame<last_frame?last_frame:first_frame;\n\n#ifndef cimg_use_tiff\n      cimg::unused(bits_per_value,voxel_size,description);\n      if (nfirst_frame || nlast_frame!=~0U || nstep_frame>1)\n        throw CImgArgumentException(_cimg_instance\n                                    \"load_tiff(): Unable to read sub-images from file '%s' unless libtiff is enabled.\",\n                                    cimg_instance,\n                                    filename);\n      return load_other(filename);\n#else\n#if cimg_verbosity<3\n      TIFFSetWarningHandler(0);\n      TIFFSetErrorHandler(0);\n#endif\n      TIFF *tif = TIFFOpen(filename,\"r\");\n      if (tif) {\n        unsigned int nb_images = 0;\n        do ++nb_images; while (TIFFReadDirectory(tif));\n        if (nfirst_frame>=nb_images || (nlast_frame!=~0U && nlast_frame>=nb_images))\n          cimg::warn(_cimg_instance\n                     \"load_tiff(): File '%s' contains %u image(s) while specified frame range is [%u,%u] (step %u).\",\n                     cimg_instance,\n                     filename,nb_images,nfirst_frame,nlast_frame,nstep_frame);","sourceCodeStart":57972,"sourceCodeEnd":58008,"githubUrl":"https://github.com/Yalantis/uCrop/blob/f788b534b48c144edf786c8cddbf0e029e637804/ucrop/src/main/jni/CImg.h#L57972-L58008","documentation":"When CImg is built without libtiff (cimg_use_tiff undefined), load_tiff() can only load a single-image file via load_other(). If the caller requests any sub-image selection (non-zero first_frame, a bounded last_frame, or step_frame > 1), the library refuses with this argument error because multi-frame reading requires libtiff.","triggerScenarios":"img.load_tiff(\"file.tif\", 2) or load_tiff(\"f.tif\", 0, 5) or load_tiff(\"f.tif\", 0, ~0U, 2) compiled without cimg_use_tiff.","commonSituations":"Building the Android/JNI project without libtiff linked, then attempting to read a specific page of a multi-page TIFF stack; a build that previously had libtiff was rebuilt without it.","solutions":["Build CImg with cimg_use_tiff defined and link against libtiff to enable multi-frame reads.","If single-image loading suffices, call load_tiff(filename) with default frame arguments (0, ~0U, 1).","Pre-decode the TIFF with another library and pass raw data to CImg."],"exampleFix":"// before (no libtiff build)\nimg.load_tiff(\"stack.tif\", 3);\n// after: default args work without libtiff\nimg.load_tiff(\"stack.tif\");","handlingStrategy":"fallback","validationCode":"#ifndef cimg_use_tiff\n  if (firstFrame != 0 || stepFrame > 1) throw std::logic_error(\"sub-image reads need libtiff build\");\n#endif","typeGuard":null,"tryCatchPattern":"try { img.load_tiff(f, frame); }\ncatch (CImgArgumentException &e) { img.load_tiff(f); /* single-image fallback */ }","preventionTips":["Define cimg_use_tiff and link libtiff when multi-page TIFFs are expected","Use default frame arguments when only the first image is needed","Document build requirements next to the loader calls"],"tags":["cimg","tiff","build-configuration"],"backgroundTag":"missing-optional-dependency","analyzedSha":"f788b534b48c144edf786c8cddbf0e029e637804","analyzedAt":"2026-09-08T08:36:04.887Z","contentChangedAt":"2026-09-08T08:36:04.887Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}