What causes "save_ffmpeg_external(): Specified filename is (null)." in Yalantis/uCrop?

Pass a non-null filename with an appropriate extension/codec, e.g. img.save_ffmpeg_external("out.avi",25,"mpeg2",2048).

Yalantis/uCrop · error · CImgArgumentException

save_ffmpeg_external(): Specified filename is (null).

Error message

save_ffmpeg_external(): Specified filename is (null).

What it means

save_ffmpeg_external() encodes the image/video by shelling out to an installed ffmpeg binary, so it requires a real output filename. It throws CImgArgumentException when the filename is null. Note ffmpeg is external: it must be on PATH (cimg::ffmpeg_path()) for the call to succeed at all.

Source

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

      return *this;
    }

    //! Save volumetric image as a video, using ffmpeg external binary.
    /**
       \param filename Filename, as a C-string.
       \param fps Video framerate.
       \param codec Video codec, as a C-string.
       \param bitrate Video bitrate.
       \note
       - Each slice of the instance image is considered to be a single frame of the output video file.
       - This method uses \c ffmpeg, an external executable binary provided by
         <a href="http://www.ffmpeg.org">FFmpeg</a>.
       It must be installed for the method to succeed.
    **/
    const CImg<T>& save_ffmpeg_external(const char *const filename, const unsigned int fps=25,
                                        const char *const codec=0, const unsigned int bitrate=2048) const {
      if (!filename)
        throw CImgArgumentException(_cimg_instance
                                    "save_ffmpeg_external(): Specified filename is (null).",
                                    cimg_instance);
      if (is_empty()) { cimg::fempty(0,filename); return *this; }

      CImgList<T> list;
      get_split('z').move_to(list);
      list.save_ffmpeg_external(filename,fps,codec,bitrate);
      return *this;
    }

    //! Save image using gzip external binary.
    /**
       \param filename Filename, as a C-string.
       \note This method uses \c gzip, an external executable binary provided by
         <a href="//http://www.gzip.org">gzip</a>.
       It must be installed for the method to succeed.
    **/
    const CImg<T>& save_gzip_external(const char *const filename) const {

View on GitHub (pinned to f788b534b4)

Solutions

Pass a non-null filename with an appropriate extension/codec, e.g. img.save_ffmpeg_external("out.avi",25,"mpeg2",2048).
Guard: if (!fname) use a default path before calling.
If you don't need ffmpeg, choose an internally implemented format instead.

Example fix

// before
img.save_ffmpeg_external(fname); // fname may be NULL
// after
if (!fname) fname = "video.avi";
img.save_ffmpeg_external(fname, 25, "mpeg2", 2048);

Defensive patterns

Strategy: validation

Validate before calling

if (!fname || !*fname) fname = "video.avi";
// optionally: ensure ffmpeg exists
if (std::system("ffmpeg -version > /dev/null 2>&1") != 0) { /* handle absence */ }
img.save_ffmpeg_external(fname, 25, "mpeg2", 2048);

Type guard

bool validOutputFile(const char *p) { return p != nullptr && p[0] != '\0'; }

Try / catch

try { img.save_ffmpeg_external(path.c_str()); }
catch (cimg_library::CImgArgumentException &e) { std::fprintf(stderr, "ffmpeg save: %s\n", e.what()); }
catch (cimg_library::CImgIOException &e) { std::fprintf(stderr, "ffmpeg failed (installed?): %s\n", e.what()); }

Prevention

Never call external-tool savers with a null filename.
Check ffmpeg availability once at startup if the feature is optional.
Catch both argument and IO exceptions around external saves.

When it happens

Trigger: Calling save_ffmpeg_external() with the default/NULL filename, or passing a null char* produced by earlier code.

Common situations: Filename composed from environment/config that was absent; calling the method on systems where the path variable was never allocated; test harnesses invoking it without arguments.

Related errors

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