Yalantis/uCrop · error · CImgArgumentException

load_ffmpeg_external(): Specified filename is (null) or does

Error message

load_ffmpeg_external(): Specified filename is (null) or does not exist.

What it means

CImgList::load_ffmpeg_external() decodes videos by shelling out to an external 'ffmpeg' binary. Before doing anything it validates the filename; if the pointer is null or cimg::is_file() reports the path does not exist as a regular file, it throws this CImgArgumentException immediately.

Source

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

                              cimglist_instance,filename,first_frame);
      return *this;
#endif
    }

    //! Load an image from a video file, using OpenCV library \newinstance.
    static CImgList<T> get_load_video(const char *const filename,
                           const unsigned int first_frame=0, const unsigned int last_frame=~0U,
                           const unsigned int step_frame=1) {
      return CImgList<T>().load_video(filename,first_frame,last_frame,step_frame);
    }

    //! Load an image from a video file using the external tool 'ffmpeg'.
    /**
      \param filename Filename to read data from.
    **/
    CImgList<T>& load_ffmpeg_external(const char *const filename) {
      if (!filename || !cimg::is_file(filename))
        throw CImgArgumentException(_cimglist_instance
                                    "load_ffmpeg_external(): Specified filename is (null) or does not exist.",
                                    cimglist_instance);
      CImg<charT> command(1024), filename_tmp(256), filename_tmp2(256);
      do {
        cimg_snprintf(filename_tmp,filename_tmp._width,"%s%c%s",
                      cimg::temporary_path(),cimg_file_separator,cimg::filenamerand());
        cimg_snprintf(filename_tmp2,filename_tmp2._width,"%s_000001.ppm",filename_tmp._data);
      } while (cimg::path_exists(filename_tmp2));
      cimg_snprintf(filename_tmp2,filename_tmp2._width,"%s_%%6d.ppm",filename_tmp._data);
      cimg_snprintf(command,command._width,"\"%s\" -v -8 -i \"%s\" \"%s\"",
                    cimg::ffmpeg_path(),
                    CImg<charT>::string(filename)._system_strescape().data(),
                    CImg<charT>::string(filename_tmp2)._system_strescape().data());
      if (cimg::system(command,cimg::ffmpeg_path())!=0)
        throw CImgIOException(_cimglist_instance
                              "load_ffmpeg_external(): Failed to open file '%s' with external command 'ffmpeg'.",
                              cimglist_instance,
                              filename);

View on GitHub (pinned to f788b534b4)

Solutions

  1. Check the file exists before calling: pass an absolute path and verify with std::filesystem::exists / access().
  2. Fix relative paths by setting/verifying the current working directory, or always use absolute paths.
  3. Copy non-file sources (URIs, streams) to a temporary local file first, then load that file.

Example fix

// before
list.load_ffmpeg_external("clip.mp4"); // cwd differs -> path not found

// after
std::string abs = std::filesystem::absolute("clip.mp4").string();
if (std::filesystem::is_regular_file(abs)) {
  list.load_ffmpeg_external(abs.c_str());
}
Defensive patterns

Strategy: validation

Validate before calling

bool usableFile(const char* p) {
  return p != nullptr && std::filesystem::is_regular_file(p);
}
if (!usableFile(path)) { /* fix path before calling */ }

Type guard

bool isExistingFile(const char* p) {
  return p != nullptr && std::filesystem::exists(p) &&
         std::filesystem::is_regular_file(p);
}

Try / catch

try {
  list.load_ffmpeg_external(path);
} catch (CImgArgumentException&) {
  // report missing/invalid path to caller
}

Prevention

When it happens

Trigger: Calling load_ffmpeg_external(nullptr) or with a path to a non-existent/removed file, a directory, or an unreadable path on systems where ffmpeg is the chosen video backend.

Common situations: Typos or wrong working directory for relative paths; file deleted between selection and load; Android native code receiving a content:// URI instead of a real filesystem path.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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