{"record":{"id":"03afbc33e9a1f7dd","repo":"Yalantis/uCrop","slug":"load-video-file-s-unable-to-locate-frame-u","errorCode":null,"errorMessage":"load_video(): File '%s', unable to locate frame %u.","messagePattern":"load_video\\(\\): File '(.+?)', unable to locate frame %u\\.","errorType":"exception","errorClass":"CImgIOException","httpStatus":null,"severity":"error","filePath":"ucrop/src/main/jni/CImg.h","lineNumber":67437,"sourceCode":"      }\n\n      if (!go_on || (nb_frames && pos>=nb_frames)) { // Close video stream when necessary\n        cimg::mutex(9);\n        captures[index]->release();\n        delete captures[index];\n        captures[index] = 0;\n        filenames[index].assign();\n        positions[index] = 0;\n        index = -1;\n        cimg::mutex(9,0);\n      }\n\n      cimg::mutex(9);\n      last_used_index = index;\n      cimg::mutex(9,0);\n\n      if (is_empty())\n        throw CImgIOException(_cimglist_instance\n                              \"load_video(): File '%s', unable to locate frame %u.\",\n                              cimglist_instance,filename,first_frame);\n      return *this;\n#endif\n    }\n\n    //! Load an image from a video file, using OpenCV library \\newinstance.\n    static CImgList<T> get_load_video(const char *const filename,\n                           const unsigned int first_frame=0, const unsigned int last_frame=~0U,\n                           const unsigned int step_frame=1) {\n      return CImgList<T>().load_video(filename,first_frame,last_frame,step_frame);\n    }\n\n    //! Load an image from a video file using the external tool 'ffmpeg'.\n    /**\n      \\param filename Filename to read data from.\n    **/\n    CImgList<T>& load_ffmpeg_external(const char *const filename) {","sourceCodeStart":67419,"sourceCodeEnd":67455,"githubUrl":"https://github.com/Yalantis/uCrop/blob/f788b534b48c144edf786c8cddbf0e029e637804/ucrop/src/main/jni/CImg.h#L67419-L67455","documentation":"In the OpenCV-backed load_video(), after seeking/reading, if the resulting CImgList is still empty CImg concludes the requested first_frame could not be located in the video and throws this CImgIOException. Typically the frame index is beyond the last frame of the video, or the capture produced no frames at all.","triggerScenarios":"Calling load_video(filename, first_frame) where first_frame >= total frame count, or where the seek (CAP_PROP_POS_FRAMES) failed and no frames were grabbed.","commonSituations":"Hard-coded frame numbers used with user-supplied clips of varying length; videos whose frame count metadata is wrong, causing a seek past the end; variable-frame-rate videos where OpenCV seeking lands nowhere.","solutions":["Query the video's frame count first (e.g. cv::VideoCapture CAP_PROP_FRAME_COUNT) and clamp first_frame/last_frame to it before calling load_video.","Retry with first_frame=0 to confirm the file decodes at all; if it does, your index is out of range.","For VFR videos, step frame-by-frame from 0 instead of seeking directly to a frame number.","Re-encode the video to constant frame rate (ffmpeg -vsync cfr) to make seeking reliable."],"exampleFix":"// before\nlist.load_video(\"clip.mp4\", 9000); // clip has ~300 frames -> throws\n\n// after\nunsigned int first = std::min<unsigned int>(9000, getFrameCount(\"clip.mp4\") - 1);\nlist.load_video(\"clip.mp4\", first);","handlingStrategy":"validation","validationCode":"// clamp frame index before loading\nunsigned int total = probeFrameCount(file); // via cv::VideoCapture or ffprobe\nif (firstFrame >= total) firstFrame = total > 0 ? total - 1 : 0;","typeGuard":null,"tryCatchPattern":"try {\n  list.load_video(file, first);\n} catch (CImgIOException&) {\n  list.load_video(file, 0); // fallback: first frame\n}","preventionTips":["Query CAP_PROP_FRAME_COUNT (or ffprobe) and clamp requested frames to the actual count.","Never hard-code frame numbers; derive them from the video metadata.","Re-encode VFR videos to constant frame rate for reliable seeking."],"tags":["cimg","opencv","video","frame-range","index-out-of-range"],"backgroundTag":"index-out-of-range","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"}